List simulations | Runledger API

{
  "object": "string",
  "data": [
    {
      "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"
    }
  ],
  "has_more": true,
  "next_cursor": "string"
}

Newest first. Simulations are kept for 30 days.

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.

Query parameters

statusenumOptional

Only simulations with this status.

Allowed values:

limitintegerOptional1-100Defaults to 20

Maximum number of objects to return, from 1 to 100.

cursorstringOptional

The next_cursor from the previous page.

Response

A page of simulations.

object"list"

datalist of objects

has_moreboolean

next_cursorstringOptional

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

429

Too Many Requests Error

500

Internal Server Error