> ## Documentation Index
> Fetch the complete documentation index at: https://leadmagic.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Check Credits

> GET /v1/credits — monitor your API credit balance programmatically.

# Credit Balance

Monitor your credit balance programmatically. Use this endpoint to:

* Track usage across your applications
* Set up alerts before running low
* Build internal dashboards

<Info>
  This endpoint is **FREE** - no credits consumed and no rate limiting applied.
</Info>

## Quick Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl 'https://api.leadmagic.io/v1/credits' \
    -H 'X-API-Key: YOUR_API_KEY'
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch('https://api.leadmagic.io/v1/credits', {
    headers: { 'X-API-Key': 'YOUR_API_KEY' }
  });
  const { credits } = await response.json();
  console.log(`Available: ${credits} credits`);
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  response = requests.get(
      'https://api.leadmagic.io/v1/credits',
      headers={'X-API-Key': 'YOUR_API_KEY'}
  )
  print(f"Credits: {response.json()['credits']}")
  ```
</CodeGroup>

## Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "credits": 15432.50
}
```

## Response Fields

| Field     | Type   | Description                 |
| --------- | ------ | --------------------------- |
| `credits` | number | Your current credit balance |

## Additional Endpoints

| Endpoint                   | Method | Description                                                      |
| -------------------------- | ------ | ---------------------------------------------------------------- |
| `GET /v1/credits`          | GET    | Get current credit balance                                       |
| `POST /v1/credits/refresh` | POST   | Force refresh credits from database (use if balance seems stale) |
| `GET /v1/credits/health`   | GET    | Validate API key and check authentication status                 |

## Best Practices

<AccordionGroup>
  <Accordion title="Cache the response" icon="database">
    Don't call this endpoint before every API request. Cache the balance and refresh periodically (e.g., every 5 minutes).

    ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
    let cachedCredits = null;
    let lastFetch = 0;
    const CACHE_TTL = 60000; // 1 minute

    async function getCredits() {
      if (cachedCredits && Date.now() - lastFetch < CACHE_TTL) {
        return cachedCredits;
      }

      const response = await fetch('https://api.leadmagic.io/v1/credits', {
        headers: { 'X-API-Key': apiKey }
      });

      const { credits } = await response.json();
      cachedCredits = credits;
      lastFetch = Date.now();
      return credits;
    }
    ```
  </Accordion>

  <Accordion title="Use response headers instead" icon="heading">
    Every API response includes `X-Credits-Remaining` header - use this instead of making a separate call:

    ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
    const response = await fetch(endpoint, options);
    const creditsRemaining = response.headers.get('X-Credits-Remaining');
    console.log(`Credits after request: ${creditsRemaining}`);
    ```
  </Accordion>

  <Accordion title="Set up alerts" icon="bell">
    Implement alerts when credits fall below a threshold to avoid service interruptions.

    ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
    const { credits } = await checkCredits();

    if (credits < 100) {
      sendCriticalAlert('CRITICAL: Credits below 100!');
    } else if (credits < 1000) {
      sendWarning('Low credit balance: ' + credits);
    }
    ```
  </Accordion>
</AccordionGroup>

## Need More Analytics?

For comprehensive usage analytics, see our [Analytics API](/docs/v1/reference/analytics) which includes:

* Real-time dashboard with rate limits and usage stats
* Daily and monthly credit consumption history
* Per-product breakdown with success rates
* Latency percentiles and error tracking

<Card title="Analytics API" icon="chart-line" href="/docs/v1/reference/analytics">
  Get detailed insights into your API usage with our comprehensive analytics suite.
</Card>


## OpenAPI

````yaml get /v1/credits
openapi: 3.1.0
info:
  title: LeadMagic API
  version: 1.4.34
  description: >
    # LeadMagic API Documentation


    The LeadMagic API provides comprehensive B2B data enrichment services
    including email validation, email finding, profile search, company
    intelligence, and more.


    ## Quick Start


    1. Get your API key from the [LeadMagic Dashboard](https://app.leadmagic.io)

    2. Add the `X-API-Key` header to all requests

    3. Start enriching your data!


    ## Base URL


    All API requests should be made to: `https://api.leadmagic.io`


    ## Rate Limits


    Each endpoint has specific rate limits (requests per minute). Exceeding
    limits returns a `429 Too Many Requests` response.


    ## Credits


    API calls consume credits based on the endpoint used. Check your balance
    with the `/v1/credits` endpoint.


    ## Support


    Contact us at support@leadmagic.io for assistance.
  contact:
    name: LeadMagic Support
    email: support@leadmagic.io
    url: https://leadmagic.io
  termsOfService: https://leadmagic.io/legal/terms
servers:
  - url: https://api.leadmagic.io
    description: Production API Server
security:
  - ApiKeyAuth: []
tags:
  - name: Credits
    description: Manage and check your credit balance
  - name: Analytics
    description: >-
      Monitor your API usage with comprehensive analytics endpoints (FREE - no
      credits consumed)
  - name: People Enrichment
    description: Find and validate contact information for individuals
  - name: Company Data
    description: Discover company information and intelligence
  - name: Jobs Data
    description: Search job listings and detect career changes
  - name: Ads Data
    description: Search advertising data across platforms
paths:
  /v1/credits:
    get:
      tags:
        - Credits
      summary: Check Credits
      description: Check your current credit balance.
      operationId: check-credits
      responses:
        '200':
          description: Successful credits retrieval
          content:
            application/json:
              schema:
                type: object
                properties:
                  credits:
                    type: number
                    example: 2200
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    Unauthorized:
      description: |
        Unauthorized - Authentication failed.

        **Common causes:**
        - Missing X-API-Key header
        - Invalid or expired API key
        - Malformed API key
      content:
        application/problem+json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/MissingAuthenticationError'
              - $ref: '#/components/schemas/InvalidApiKeyError'
  schemas:
    MissingAuthenticationError:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
      example:
        success: false
        errors:
          - type: https://api.leadmagic.io/errors/missing_authentication
            title: >-
              Authentication required. Provide a valid API key in the X-API-Key
              header (case-insensitive).
            status: 401
            code: missing_authentication
            docs: https://leadmagic.io/docs/api-reference/authentication
        meta:
          request_id: ea6e3248-f4d2-437d-bca3-20881b529129
          timestamp: '2024-02-01T12:00:00.000Z'
    InvalidApiKeyError:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
      example:
        success: false
        errors:
          - type: https://api.leadmagic.io/errors/invalid_api_key
            title: Invalid API key. The key does not exist or is incorrect.
            status: 401
            code: invalid_api_key
            docs: https://leadmagic.io/docs/api-reference/authentication
        meta:
          request_id: ea6e3248-f4d2-437d-bca3-20881b529129
          timestamp: '2024-02-01T12:00:00.000Z'
    ErrorResponse:
      type: object
      description: RFC 9457 Problem Details error response
      required:
        - success
        - errors
      properties:
        success:
          type: boolean
          example: false
          description: Always false for error responses
        errors:
          type: array
          description: Array of error details (typically one, but can be multiple)
          items:
            $ref: '#/components/schemas/ErrorDetail'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
    ErrorDetail:
      type: object
      description: RFC 9457 compliant error detail
      required:
        - type
        - title
        - status
      properties:
        type:
          type: string
          format: uri
          description: RFC 9457 - URI reference identifying the error type
          example: https://api.leadmagic.io/errors/validation_error
        title:
          type: string
          description: RFC 9457 - Short human-readable summary
          example: Request validation failed. Check your input parameters.
        status:
          type: integer
          description: RFC 9457 - HTTP status code
          example: 400
        detail:
          type: string
          description: RFC 9457 - Human-readable explanation specific to this occurrence
          example: The email field is required but was not provided.
        instance:
          type: string
          format: uri
          description: RFC 9457 - URI reference for this specific occurrence
          example: /v1/people/email-validation#req_abc123
        code:
          type: string
          description: Machine-readable error code for programmatic handling
          example: validation_error
        param:
          type: array
          description: Parameters that caused the error
          items:
            type: string
          example:
            - email
        action:
          type: string
          description: Suggested action to resolve the error
          example: Provide a valid email address in the 'email' field.
        docs:
          type: string
          format: uri
          description: Link to relevant documentation
          example: https://leadmagic.io/docs/api-reference/errors
        context:
          type: object
          description: Additional context specific to this error type
          additionalProperties: true
    ResponseMeta:
      type: object
      description: Metadata included in all responses
      properties:
        request_id:
          type: string
          format: uuid
          description: Unique identifier for this request (use for debugging/support)
          example: ea6e3248-f4d2-437d-bca3-20881b529129
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the response was generated
          example: '2024-02-01T12:00:00.000Z'
        environment:
          type: string
          description: API environment (production, staging)
          example: production
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        Your LeadMagic API key. Header name is case-insensitive (X-API-Key,
        X-API-KEY, x-api-key all work).

````