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

# Get Credits Balance

> Retrieve the current credit balance for the authenticated organization

This endpoint returns the current credit balance for the organization associated with the authenticated user. Credits are used for various enrichment operations within the platform.

## Authentication

<Note>
  This endpoint requires authentication. The organization ID is automatically
  determined from the authenticated session.
</Note>

## Request

This endpoint does not require any request parameters. The organization is identified automatically from the authentication context.

## Response

<ResponseField name="balance" type="integer" required>
  The current credit balance for the organization. This is a non-negative
  integer representing the total available credits. **Example:** `1500`
</ResponseField>

<ResponseField name="organizationId" type="string" required>
  The unique identifier of the organization whose balance was retrieved.
  **Example:** `org_2abc123def456`
</ResponseField>

## Credit Usage

Credits are consumed when performing enrichment operations:

| Operation Type        | Description                         |
| --------------------- | ----------------------------------- |
| `enrichment_email`    | Email address enrichment            |
| `enrichment_phone`    | Phone number enrichment             |
| `enrichment_combined` | Combined email and phone enrichment |
| `linkedin_enrichment` | LinkedIn profile enrichment         |

## Credit Sources

Credits can be added to an organization through several sources:

| Source                | Description                         |
| --------------------- | ----------------------------------- |
| `stripe_subscription` | Monthly subscription allocation     |
| `stripe_purchase`     | One-time credit purchase            |
| `signup_bonus`        | Welcome bonus for new organizations |
| `manual`              | Manual credit adjustment by admin   |

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://app.lance.so/api/v1/operations/credits/balance" \
    -H "Authorization: Bearer <token>"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("/api/v1/operations/credits/balance", {
    method: "GET",
    headers: {
      Authorization: "Bearer <token>",
    },
  });

  const data = await response.json();
  console.log(`Balance: ${data.balance} credits`);
  ```

  ```typescript TypeScript theme={null}
  interface CreditBalance {
    balance: number;
    organizationId: string;
  }

  const response = await fetch("/api/v1/operations/credits/balance", {
    method: "GET",
    headers: {
      Authorization: "Bearer <token>",
    },
  });

  const data: CreditBalance = await response.json();
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={null}
  {
    "balance": 1500,
    "organizationId": "org_2abc123def456"
  }
  ```

  ```json Error Response (Unauthorized) theme={null}
  {
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "Organization ID is required"
    }
  }
  ```

  ```json Error Response (Server Error) theme={null}
  {
    "error": {
      "code": "INTERNAL_ERROR",
      "message": "An unexpected error occurred"
    }
  }
  ```
</ResponseExample>

## Error Codes

| Status Code | Error Code         | Description                                                      |
| ----------- | ------------------ | ---------------------------------------------------------------- |
| `400`       | `VALIDATION_ERROR` | User is not authenticated or not associated with an organization |
| `500`       | `INTERNAL_ERROR`   | Server error while retrieving balance                            |

## Notes

* The balance is calculated as the sum of all credit transactions (additions minus consumptions) for the organization
* Balance can be zero but never negative - the system prevents operations that would result in negative balance
* New organizations receive a signup bonus upon first access