Retrieve a simulation | Runledger API

{
  "id": "sim_5wD2nF8qTj",
  "object": "string",
  "status": "pending",
  "from": "2024-01-15T09:30:00Z",
  "to": "2024-01-15T09:30:00Z",
  "currency": "usd",
  "livemode": true,
  "created_at": "2024-01-15T09:30:00Z",
  "group_by": "customer",
  "document": {
    "cost_models": [
      {
        "key": "vidlab-v2",
        "name": "Vidlab v2 video",
        "source": "catalog",
        "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"
          }
        ],
        "provider": "vidlab",
        "model": "vidlab-v2",
        "kind": "text",
        "units": [
          {
            "unit": "video_seconds",
            "controlled_by": "customer",
            "description": "string"
          }
        ],
        "dimensions": [
          {
            "key": "resolution",
            "controlled_by": "customer",
            "values": [
              "720p",
              "1080p"
            ],
            "description": "string"
          }
        ],
        "rate_card": {
          "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_reference": "Vidlab pricing page, read 20 October 2026"
        },
        "metadata": {}
      }
    ],
    "price_rules": [
      {
        "name": "string",
        "currency": "usd",
        "key": "video_cost_plus",
        "method": "cost_plus",
        "description": "string",
        "basis": "catalog",
        "inputs": [
          {
            "cost_model": "vidlab-v2",
            "unit": "video_seconds",
            "quantity_from": "quantity"
          }
        ],
        "markup_percent": "0.4",
        "target_margin_percent": "0.3",
        "rows": [
          {
            "dimensions": {
              "resolution": "1080p"
            },
            "unit_amount_decimal": "20",
            "tier_mode": "graduated",
            "tiers": [
              {
                "unit_amount_decimal": "300",
                "up_to": "200000"
              }
            ]
          }
        ],
        "formula": "max(cost * 1.4, 50)",
        "floor_decimal": "50",
        "cap_decimal": "string",
        "credit_value_decimal": "1",
        "on_cost_change": "hold",
        "effective_from": "2024-01-15T09:30:00Z"
      }
    ],
    "margin_guardrails": [
      {
        "name": "string",
        "min_margin_percent": "0.25",
        "key": "video_margin_floor",
        "applies_to": {
          "event_name": "video.generate",
          "outcome_definition": "string",
          "plan": "string"
        },
        "basis": "expected",
        "action": "warn",
        "window": "P7D",
        "enabled": true
      }
    ]
  },
  "cost_adjustments": [
    {
      "cost_model": "string",
      "unit": "string",
      "multiplier": "1.2",
      "catalog_price": "catp_9cW4hL6rBv"
    }
  ],
  "results": {
    "events_considered": 1,
    "costs_considered": 1,
    "events_unpriced": 1,
    "baseline": {
      "revenue_confirmed": "41200",
      "revenue_pending": "0",
      "revenue_reversed": "0",
      "cost": "27650",
      "margin": "13550",
      "margin_percent": "0.3289"
    },
    "candidate": {
      "revenue_confirmed": "41200",
      "revenue_pending": "0",
      "revenue_reversed": "0",
      "cost": "27650",
      "margin": "13550",
      "margin_percent": "0.3289"
    },
    "by_group": [
      {
        "group": "string",
        "baseline": {
          "revenue_confirmed": "41200",
          "revenue_pending": "0",
          "revenue_reversed": "0",
          "cost": "27650",
          "margin": "13550",
          "margin_percent": "0.3289"
        },
        "candidate": {
          "revenue_confirmed": "41200",
          "revenue_pending": "0",
          "revenue_reversed": "0",
          "cost": "27650",
          "margin": "13550",
          "margin_percent": "0.3289"
        }
      }
    ],
    "guardrails": [
      {
        "key": "string",
        "would_warn": 1,
        "would_block": 1
      }
    ],
    "warnings": [
      {
        "code": "confirmation_window_short",
        "message": "The charge confirms almost at once, so only the reversal horizon protects you.",
        "path": "outcome_definitions.0.confirmation_window"
      }
    ]
  },
  "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"
  },
  "actor": {
    "type": "user",
    "id": "usr_4tN8vB2cXk",
    "name": "Claude Code",
    "on_behalf_of": "usr_4tN8vB2cXk",
    "client": "claude-code"
  },
  "completed_at": "2024-01-15T09:30:00Z"
}

Returns one simulation and its result.

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

simulation_idstringRequired

The simulation ID (sim_...).

Response

The simulation.

idstring

object"simulation"

statusenum

Allowed values:

fromdatetime

todatetime

currencystring

livemodeboolean

created_atdatetime

group_byenumOptional

Allowed values:

documentobjectOptional

The candidate. Sections have the shape of the matching create requests, and replace the current object with the same key for the simulation only.

cost_adjustmentslist of objectsOptional

resultsobjectOptional

Present when status is completed.

errorobjectOptional

Present when status is failed.

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.

completed_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