> ## 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 Credit History

> Retrieve the credit transaction history for your organization

## Overview

Returns a paginated list of credit transactions for the authenticated organization. Transactions include credit additions (from subscriptions, purchases, or bonuses) and credit consumption (from enrichment operations).

## Authentication

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

## Query Parameters

<ParamField query="startDate" type="string" optional>
  Filter transactions from this date onwards. Must be a valid ISO 8601 date
  string. Example: `2025-01-01T00:00:00.000Z`
</ParamField>

<ParamField query="endDate" type="string" optional>
  Filter transactions up to this date. Must be a valid ISO 8601 date string.
  Example: `2025-01-31T23:59:59.999Z`
</ParamField>

<ParamField query="limit" type="integer" optional default="100000">
  Maximum number of transactions to return. Must be a positive integer with a
  maximum value of 100,000.
</ParamField>

<ParamField query="offset" type="integer" optional default="0">
  Number of transactions to skip for pagination. Must be a non-negative integer.
</ParamField>

## Response

<ResponseField name="transactions" type="array" required>
  Array of credit transaction objects.

  <Expandable title="Transaction Object">
    <ResponseField name="id" type="string" required>
      Unique identifier (UUID) for the transaction.
    </ResponseField>

    <ResponseField name="organizationId" type="string" required>
      The organization ID this transaction belongs to.
    </ResponseField>

    <ResponseField name="type" type="string" required>
      The type of transaction. One of: - `credit_added` - Credits were added to
      the account - `credit_consumed` - Credits were used for an operation -
      `adjustment` - Manual adjustment to credits
    </ResponseField>

    <ResponseField name="amount" type="integer" required>
      The number of credits involved in this transaction. Always a non-negative
      integer.
    </ResponseField>

    <ResponseField name="operationType" type="string | null">
      For consumption transactions, indicates the operation type: -
      `enrichment_email` - Email enrichment - `enrichment_phone` -
      Phone enrichment - `enrichment_combined` - Combined email and
      phone enrichment - `linkedin_enrichment` - LinkedIn profile enrichment.
      Null for non-consumption transactions.
    </ResponseField>

    <ResponseField name="source" type="string | null">
      For credit additions, indicates the source: - `stripe_subscription` -
      Monthly subscription credits - `stripe_purchase` - One-time credit
      purchase - `signup_bonus` - Initial signup bonus (250 credits) - `manual`

      * Manual credit adjustment Null for consumption transactions.
    </ResponseField>

    <ResponseField name="referenceId" type="string | null">
      External reference ID (e.g., Stripe payment ID) for tracking purposes.
    </ResponseField>

    <ResponseField name="description" type="string | null">
      Human-readable description of the transaction.
    </ResponseField>

    <ResponseField name="metadata" type="object | null">
      Additional metadata associated with the transaction. For consumption
      transactions, may include: - `count` - Number of operations performed -
      `costPerOperation` - Credit cost per individual operation
    </ResponseField>

    <ResponseField name="createdAt" type="string" required>
      ISO 8601 timestamp of when the transaction was created.
    </ResponseField>

    <ResponseField name="updatedAt" type="string" required>
      ISO 8601 timestamp of when the transaction was last updated.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="count" type="integer" required>
  The number of transactions returned in this response.
</ResponseField>

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://app.lance.so/api/v1/operations/credits/history?limit=10&offset=0" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch(
    "/api/v1/operations/credits/history?limit=10&startDate=2025-01-01T00:00:00.000Z",
    {
      headers: {
        Authorization: `Bearer ${token}`,
      },
    }
  );

  const data = await response.json();
  ```
</CodeGroup>

## Example Response

<CodeGroup>
  ```json Success (200) theme={null}
  {
    "transactions": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "organizationId": "org_abc123",
        "type": "credit_consumed",
        "amount": 50,
        "operationType": "enrichment_email",
        "source": null,
        "referenceId": null,
        "description": "10 x enrichment_email (5 credits each)",
        "metadata": {
          "count": 10,
          "costPerOperation": 5
        },
        "createdAt": "2025-01-13T10:30:00.000Z",
        "updatedAt": "2025-01-13T10:30:00.000Z"
      },
      {
        "id": "550e8400-e29b-41d4-a716-446655440001",
        "organizationId": "org_abc123",
        "type": "credit_added",
        "amount": 1000,
        "operationType": null,
        "source": "stripe_subscription",
        "referenceId": "sub_1234567890",
        "description": "Monthly subscription credits",
        "metadata": null,
        "createdAt": "2025-01-01T00:00:00.000Z",
        "updatedAt": "2025-01-01T00:00:00.000Z"
      }
    ],
    "count": 2
  }
  ```

  ```json Unauthorized (401) theme={null}
  {
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "Organization ID is required"
    }
  }
  ```
</CodeGroup>

## Error Codes

| Status | Code               | Description                                                                 |
| ------ | ------------------ | --------------------------------------------------------------------------- |
| 401    | `VALIDATION_ERROR` | Organization ID is required (user not authenticated)                        |
| 400    | `VALIDATION_ERROR` | Invalid query parameters (e.g., invalid date format, limit exceeds 100,000) |
| 500    | `INTERNAL_ERROR`   | An unexpected server error occurred                                         |

## Credit Costs Reference

| Operation           | Cost (Credits) |
| ------------------- | -------------- |
| Email Enrichment    | 5              |
| Phone Enrichment    | 20             |
| Combined Enrichment | 25             |
| LinkedIn Enrichment | 1              |