Trace model calls in a batch

POST

https://api.runledger.co/v1/costs/batch

POST

/v1/costs/batch

curl -X POST https://api.runledger.co/v1/costs/batch \
     -H "Authorization: Bearer <api_key>" \
     -H "Content-Type: application/json" \
     -d '{
  "costs": [
    {
      "idempotency_key": "string",
      "provider": "anthropic",
      "model": "claude-sonnet-5-5"
    }
  ]
}'

{
  "object": "string",
  "results": [
    {
      "idempotency_key": "string",
      "status": "created",
      "cost": {
        "id": "cost_8Jq3vB6yDs",
        "object": "string",
        "idempotency_key": "string",
        "provider": "string",
        "model": "string",
        "priced_by": "request",
        "timestamp": "2024-01-15T09:30:00Z",
        "livemode": true,
        "created_at": "2024-01-15T09:30:00Z",
        "run_id": "string",
        "customer": "string",
        "agent_id": "string",
        "member_id": "string",
        "team_id": "string",
        "usage": {
          "input_tokens": 1840,
          "output_tokens": 512,
          "cache_read_tokens": 1,
          "cache_write_tokens": 1,
          "reasoning_tokens": 1
        },
        "lines": [
          {
            "unit": "string",
            "quantity": "string",
            "dimensions": {},
            "cost_model": "cm_6bR3xN8vQe",
            "rate_card": "rc_4tG9wK2nPd",
            "rate_card_version": 1,
            "rate_source": "catalog",
            "override": "textco_negotiated",
            "catalog_price": "catp_9cW4hL6rBv",
            "cost": {
              "amount_decimal": "0.042",
              "currency": "usd"
            }
          }
        ],
        "cost": {
          "amount_decimal": "0.042",
          "currency": "usd"
        },
        "warnings": [
          {
            "code": "no_rate_for_event",
            "message": "string"
          }
        ],
        "metadata": {}
      },
      "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"
      }
    }
  ]
}

Records up to 100 costs in one request. Each succeeds or fails on its own.

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.

costslist of objectsRequired

Response

One result per submitted cost.

object"cost_batch"

resultslist of objects

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