Retrieve a cost model | Runledger API

{
  "id": "cm_6bR3xN8vQe",
  "object": "string",
  "key": "vidlab-v2",
  "name": "string",
  "source": "catalog",
  "provider": "vidlab",
  "model": "vidlab-v2",
  "status": "active",
  "units": [
    {
      "unit": "video_seconds",
      "controlled_by": "customer",
      "description": "string"
    }
  ],
  "dimensions": [
    {
      "key": "resolution",
      "controlled_by": "customer",
      "values": [
        "720p",
        "1080p"
      ],
      "description": "string"
    }
  ],
  "livemode": true,
  "created_at": "2024-01-15T09:30:00Z",
  "catalog_model": "catm_5xT7qD2mKa",
  "overrides": [
    {
      "key": "textco_negotiated",
      "unit": "input_tokens",
      "dimensions": {
        "resolution": "1080p"
      },
      "discount_percent": "0.2",
      "unit_amount_decimal": "10",
      "per": "1",
      "effective_from": "2024-01-15T09:30:00Z",
      "effective_to": "2024-01-15T09:30:00Z",
      "category": "negotiated_discount",
      "reason": "Negotiated 20% off to 31 December 2026"
    }
  ],
  "kind": "text",
  "active_rate_card": "string",
  "active_rate_card_version": 1,
  "metadata": {},
  "actor": {
    "type": "user",
    "id": "usr_4tN8vB2cXk",
    "name": "Claude Code",
    "on_behalf_of": "usr_4tN8vB2cXk",
    "client": "claude-code"
  }
}

Takes the ID or the key.

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

cost_modelstringRequired

The cost model ID (cm_...) or its key.

Response

The cost model.

idstring

object"cost_model"

keystring

namestring

sourceenum

Where a cost model’s rates come from. catalog: the provider price catalog that Runledger maintains, with your overrides on top. custom: rate cards you enter yourself.

Allowed values:

providerstring

modelstring

statusenum

Allowed values:

unitslist of objects

dimensionslist of objects

livemodeboolean

created_atdatetime

catalog_modelstringOptional

For source: catalog. The catalog model this cost model follows (catm_...).

overrideslist of objectsOptional

Your overrides of the catalog rates. Always empty for a custom cost model.

kindenumOptional

What the model produces. Open: new values may be added.

active_rate_cardstringOptional

The rate card in force now (rc_...). Left out until one is active.

active_rate_card_versionintegerOptional

metadatamap from strings to stringsOptional

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

actorobjectOptional

Who made a change. Runledger fills it in from the credential, so a client can’t claim to be someone else: an API key always acts as itself, the dashboard calls the API as the signed-in person, and the MCP server passes the client’s name and the person it acts for. A request that sends a Runledger-Actor header is refused with 400 parameter_unknown.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

429

Too Many Requests Error

500

Internal Server Error