Retrieve a catalog model

GET

https://api.runledger.co/v1/catalog/models/:catalog_model

GET

/v1/catalog/models/:catalog_model

curl https://api.runledger.co/v1/catalog/models/catalog_model \
     -H "Authorization: Bearer <api_key>"

{
  "id": "catm_5xT7qD2mKa",
  "object": "string",
  "provider": "vidlab",
  "model": "vidlab-v2",
  "name": "Vidlab v2 video",
  "status": "active",
  "units": [
    {
      "unit": "video_seconds",
      "controlled_by": "customer",
      "description": "string"
    }
  ],
  "dimensions": [
    {
      "key": "resolution",
      "controlled_by": "customer",
      "values": [
        "720p",
        "1080p"
      ],
      "description": "string"
    }
  ],
  "last_verified_at": "2024-01-15T09:30:00Z",
  "kind": "text",
  "current_price": "string",
  "current_price_version": 1,
  "price": {
    "id": "catp_9cW4hL6rBv",
    "object": "string",
    "catalog_model": "catm_5xT7qD2mKa",
    "version": 1,
    "status": "scheduled",
    "currency": "usd",
    "rates": [
      {
        "unit": "video_seconds",
        "per": "1",
        "unit_amount_decimal": "12",
        "dimensions": {
          "resolution": "1080p"
        },
        "tier_mode": "graduated",
        "tiers": [
          {
            "unit_amount_decimal": "300",
            "up_to": "200000"
          }
        ]
      }
    ],
    "effective_from": "2024-01-15T09:30:00Z",
    "as_of": "2026-10-20",
    "source_url": "https://vidlab.example/pricing",
    "published_at": "2024-01-15T09:30:00Z",
    "last_verified_at": "2024-01-15T09:30:00Z",
    "effective_to": "2024-01-15T09:30:00Z",
    "source_reference": "Vidlab pricing page, read 20 October 2026",
    "changes": [
      {
        "path": "outcome_definitions.chat_resolution.confirmation_window",
        "before": null,
        "after": null
      }
    ]
  },
  "updated_at": "2024-01-15T09:30:00Z"
}

One catalog model with the price version in force expanded as price: the rates, the source, and when the rates take effect. Needs config:read.

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

catalog_modelstringRequired

The catalog model ID (catm_...).

Response

The catalog model.

idstring

object"catalog_model"

providerstring

The provider key.

modelstring

The model ID as the provider names it, as trace() sends it.

namestring

statusenum

active: priced and kept current. deprecated: the provider has retired or replaced it. Existing cost models keep working with the last price version, and no new price versions are published.

Allowed values:

unitslist of objects

dimensionslist of objects

last_verified_atdatetime

When Runledger last checked this model's prices against their source.

kindenumOptional

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

current_pricestringOptional

The price version in force now (catp_...). Left out until one is.

current_price_versionintegerOptional

priceobjectOptional

The price version in force, expanded. Only on retrieve.

updated_atdatetimeOptional

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

429

Too Many Requests Error

500

Internal Server Error