Create an export

POST

https://api.runledger.co/v1/exports

POST

/v1/exports

curl -X POST https://api.runledger.co/v1/exports \
     -H "Authorization: Bearer <api_key>" \
     -H "Content-Type: application/json" \
     -d '{
  "type": "balances",
  "format": "csv"
}'

{
  "id": "exp_4wE7rT0yUp",
  "object": "string",
  "type": "balances",
  "format": "csv",
  "status": "pending",
  "livemode": true,
  "created_at": "2024-01-15T09:30:00Z",
  "source": "api",
  "row_count": 1,
  "download_url": "string",
  "download_expires_at": "2024-01-15T09:30:00Z",
  "error": {
    "type": "https://docs.runledger.co/reference/idempotency-and-errors#error-codes",
    "title": "Insufficient balance",
    "status": 402,
    "code": "invalid_request",
    "request_id": "req_7Hc2Lq0vTz8d",
    "retryable": true,
    "detail": "The hold needs 400 ai_credits but 120 are available.",
    "param": "events.3.timestamp",
    "required_scope": "config:write",
    "errors": [
      {
        "code": "confirmation_window_short",
        "message": "The charge confirms almost at once, so only the reversal horizon protects you.",
        "path": "outcome_definitions.0.confirmation_window"
      }
    ],
    "blocked_by": [
      {
        "object": "routing_rule",
        "id": "rr_3vT8nK2xWa"
      }
    ],
    "doc_url": "https://docs.runledger.co/reference/idempotency-and-errors#error-codes"
  },
  "completed_at": "2024-01-15T09:30:00Z"
}

Starts a file export of balances, ledger entries, outcome charges or revenue. Exports run in the background; export.ready fires when the file can be downloaded. Every customer’s balance can be exported at any time, so your records never depend on Runledger staying available.

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.

Request

This endpoint expects an object.

typeenumRequired

Allowed values:

formatenumRequired

Allowed values:

as_ofdatetimeOptional

balances only: balances as they stood at this time. Defaults to now.

period_startdatetimeOptional

Required for every type except balances.

period_enddatetimeOptional

customer_idstringOptional

Limit the export to one customer.

Response

The pending export.

idstring

object"export"

typeenum

Allowed values:

formatenum

Allowed values:

statusenum

pending while the worker writes the file, ready once it can be downloaded, failed with error saying why, and expired once the file has been removed, seven days after it was ready; create the export again for a fresh file.

Allowed values:

livemodeboolean

created_atdatetime

sourceenum

How the export was created: dashboard for a person in the dashboard, api for a call to POST /v1/exports with an ordinary key, agent for a call made by an agent (an agent key or the MCP server). Returned by GET /v1/exports and GET /v1/exports/{export_id}.

Allowed values:

row_countintegerOptional

download_urlstringOptionalformat: "uri"

Present when ready, on GET /v1/exports/{export_id}. Left out of GET /v1/exports. Expires after an hour; retrieve the export again for a fresh one.

download_expires_atdatetimeOptional

When download_url stops working.

errorobjectOptional

An RFC 9457 problem details object with Runledger's extension members.

completed_atdatetimeOptional

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

409

Conflict Error

422

Unprocessable Entity Error

429

Too Many Requests Error

500

Internal Server Error