Get Credit History

curl --request GET \
  --url https://api.example.com/api/v1/operations/credits/history \
  --header 'Authorization: Bearer <token>'

{
  "transactions": [
    {
      "id": "<string>",
      "organizationId": "<string>",
      "type": "<string>",
      "amount": 123,
      "operationType": {},
      "source": {},
      "referenceId": {},
      "description": {},
      "metadata": {},
      "createdAt": "<string>",
      "updatedAt": "<string>"
    }
  ],
  "count": 123
}

GET

api

operations

credits

history

Get Credit History

curl --request GET \
  --url https://api.example.com/api/v1/operations/credits/history \
  --header 'Authorization: Bearer <token>'

{
  "transactions": [
    {
      "id": "<string>",
      "organizationId": "<string>",
      "type": "<string>",
      "amount": 123,
      "operationType": {},
      "source": {},
      "referenceId": {},
      "description": {},
      "metadata": {},
      "createdAt": "<string>",
      "updatedAt": "<string>"
    }
  ],
  "count": 123
}

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

This endpoint requires authentication. The organization ID is automatically extracted from the authenticated session.

Query Parameters

startDate

string

Filter transactions from this date onwards. Must be a valid ISO 8601 date string. Example: 2025-01-01T00:00:00.000Z

endDate

string

Filter transactions up to this date. Must be a valid ISO 8601 date string. Example: 2025-01-31T23:59:59.999Z

limit

integer

default:"100000"

Maximum number of transactions to return. Must be a positive integer with a maximum value of 100,000.

offset

integer

default:"0"

Number of transactions to skip for pagination. Must be a non-negative integer.

Response

transactions

array

required

Array of credit transaction objects.

Show Transaction Object

string

required

Unique identifier (UUID) for the transaction.

organizationId

string

required

The organization ID this transaction belongs to.

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

amount

integer

required

The number of credits involved in this transaction. Always a non-negative integer.

operationType

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.

source

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.

referenceId

string | null

External reference ID (e.g., Stripe payment ID) for tracking purposes.

description

string | null

Human-readable description of the transaction.

metadata

object | null

Additional metadata associated with the transaction. For consumption transactions, may include: - count - Number of operations performed - costPerOperation - Credit cost per individual operation

createdAt

string

required

ISO 8601 timestamp of when the transaction was created.

updatedAt

string

required

ISO 8601 timestamp of when the transaction was last updated.

count

integer

required

The number of transactions returned in this response.

Example Request

curl -X GET "https://app.lance.so/api/v1/operations/credits/history?limit=10&offset=0" \
  -H "Authorization: Bearer YOUR_TOKEN"

Example Response

{
  "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
}

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

Get Credits Balance List Payment Plans

​Overview

​Authentication

​Query Parameters

​Response

​Example Request

​Example Response

​Error Codes

​Credit Costs Reference

Overview

Authentication

Query Parameters

Response

Example Request

Example Response

Error Codes

Credit Costs Reference