Retrieve a credit grant | Runledger API

{
  "id": "cg_6tY9pZ3nVb",
  "object": "string",
  "customer": "string",
  "credit_type": "string",
  "amount": "10000",
  "remaining": "8700",
  "category": "paid",
  "priority": 1,
  "effective_at": "2024-01-15T09:30:00Z",
  "status": "scheduled",
  "source": "api",
  "metadata": {},
  "livemode": true,
  "created_at": "2024-01-15T09:30:00Z",
  "cost_basis": {
    "amount_decimal": "0.042",
    "currency": "usd"
  },
  "expires_at": "2024-01-15T09:30:00Z",
  "source_id": "string",
  "pool": "purchased",
  "allowance": "string",
  "actor": {
    "type": "user",
    "id": "usr_4tN8vB2cXk",
    "name": "Claude Code",
    "on_behalf_of": "usr_4tN8vB2cXk",
    "client": "claude-code"
  },
  "voided_at": "2024-01-15T09:30:00Z",
  "void_reason": "string",
  "voided_by": {
    "type": "user",
    "id": "usr_4tN8vB2cXk",
    "name": "Claude Code",
    "on_behalf_of": "usr_4tN8vB2cXk",
    "client": "claude-code"
  }
}

Authentication

AuthorizationBearer

A secret key (rl_sk_test_..., rl_sk_live_...) or a restricted key with limited scopes (rl_rk_test_..., rl_rk_live_...). A restricted key can carry agent: true and an expires_at, and is what a coding agent should hold. Keys end in a checksum so secret scanners can recognize them. People create, roll and revoke keys in the dashboard; GET /v1/api_keys lists them, masked.

Path parameters

credit_grant_idstringRequired

The credit grant ID (cg_...).

Response

The grant.

idstring

object"credit_grant"

customerstring

credit_typestring

amountstring

Credits granted.

remainingstring

Credits not yet drawn, expired or voided.

categoryenum

paid credits carry a cost basis and count as deferred revenue until used. promotional credits are free.

Allowed values:

priorityinteger

effective_atdatetime

statusenum

Allowed values:

sourceenum

What created the grant.

metadatamap from strings to strings

Up to 50 keys of your own, with keys up to 40 characters and values up to 500 characters.

livemodeboolean

created_atdatetime

cost_basisobjectOptional

An amount of money that can hold fractions of a minor unit, such as a per-token cost.

expires_atdatetimeOptional

When unused credits expire. A top-up or auto top-up grant always has one: one year after payment completes by default, or as the plan’s top_up.credits_expire_in or the checkout session’s credits_expire_in sets. Left out only on a grant created with POST /v1/credit_grants and no expires_at.

source_idstringOptional

The checkout session, subscription, allowance or earlier grant behind it.

poolstringOptional

The pool the credits sit in.

allowancestringOptional

The allowance key behind a grant with source: allowance, or its rollover.

actorobjectOptional

Who created the grant, when a person or agent did.

voided_atdatetimeOptional

void_reasonstringOptional

voided_byobjectOptional

Who voided it.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

429

Too Many Requests Error

500

Internal Server Error