---
title: "List credit transactions"
method: GET
path: "/v1/billing/transactions"
tags: ["Billing"]
---

# List credit transactions

`GET /v1/billing/transactions`

## Request

- Base URL: `https://api.recruitmcp.com`
- URL: `https://api.recruitmcp.com/v1/billing/transactions`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://recruitmcp.com/oauth/authorize`, token URL `https://recruitmcp.com/oauth/token`, scopes: `account:read`)

Credit grants, purchases, usage, and expiries, newest first. A customer-bound key sees the account ledger. Upstream cost rows are omitted. kind filters to grant, purchase, usage, or expiry. description says what the row is. A profile enrich that did not finish or found nothing is returned as a positive grant with a description that the credits were returned. request_id is the X-Request-Id of the API or MCP call that caused the charge; for an async enrich or contact lookup it is the call that started the job, and job_id names that job. Both are null when unknown, for example on older rows.

Scope: `account:read`.

## Query parameters

- `kind` 'grant' | 'purchase' | 'usage' | 'expiry'
- `limit` integer
- `cursor` string

## Headers

- `RecruitMCP-Version` '2026-10-13'
- `RecruitMCP-Customer` string

## Response `200`

Ledger rows.

- CreditTransactionList
  - `object` 'list', required
  - `data` CreditTransaction[], required
    - `id` string, required
    - `object` 'credit_transaction', required
    - `kind` 'grant' | 'purchase' | 'usage' | 'expiry', required
    - `purpose` string, required: Ledger purpose, for example signup_grant, stripe_purchase, or sourcing_lead.
    - `description` string, required: What this row is. A returned profile enrich says the credits were returned, not that new credits were granted.
    - `credits` number, required: Signed credits. Purchases and grants are positive. Usage and expiry are negative.
    - `created_at` string, date-time, required
    - `api_key_id` string, nullable
    - `run_id` string, nullable
    - `customer_id` string, nullable, required: Customer this row was charged to, when the ledger recorded one.
    - `request_id` string, nullable, required: X-Request-Id of the API or MCP call that caused this charge. For a job, the call that started it. null when unknown, for example on older rows and on purchases.
    - `job_id` string, nullable, required: Job that charged this row (GET /v1/jobs/{job_id} or GET /v1/contacts/jobs/{job_id}). null when the charge was not made by a job.
  - `next_cursor` string, nullable, required: Pass as cursor for the next page. Null on the last page.
  - `has_more` boolean, required

## Other responses

- `400`: `invalid_request` (do not retry): A field is missing or has a value this endpoint does not accept. `unsupported_version` (do not retry): RecruitMCP-Version is not a supported version.
- `401`: `unauthorized` (do not retry): Missing bearer API key.
- `403`: `forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.
- `429`: `rate_limited` (retry): Per-key rate limit exceeded.

## Changes

- **2026-10-20** `ad27b35513a6`: 4 warning
  - added the new `approval_forced` enum value to the `error/code` response property for the response status `400`
  - added the new `approval_forced` enum value to the `error/code` response property for the response status `401`
  - added the new `approval_forced` enum value to the `error/code` response property for the response status `403`
  - added the new `approval_forced` enum value to the `error/code` response property for the response status `429`

[Operation history](https://skmtc.dev/recruitmcp/apis/recruitmcp-api/changes/v1/billing/transactions/get.md)

---

[API](https://skmtc.dev/recruitmcp/apis/recruitmcp-api.md) · [All operations](https://skmtc.dev/recruitmcp/apis/recruitmcp-api/llms.txt) · [OpenAPI document](https://skmtc.dev/recruitmcp/apis/recruitmcp-api/revisions/ad27b35513a6?raw)