List configuration proposals

GET

https://api.runledger.co/v1/config_proposals

GET

/v1/config_proposals

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

{
  "object": "string",
  "data": [
    {
      "id": "cprop_2vK7nR4tYa",
      "object": "string",
      "status": "pending",
      "document": {
        "credit_types": [
          {
            "key": "ai_credits",
            "name": "AI credits",
            "kind": "custom",
            "currency": "string",
            "decimal_places": 2,
            "unit_label": "credit",
            "metadata": {}
          }
        ],
        "outcome_definitions": [
          {
            "key": "chat_resolution",
            "name": "Chat resolution",
            "event_name": "resolution.chat",
            "criteria": "The customer did not reply within 24 hours and did not ask for a person.",
            "preset": "support_chat",
            "confirmation_window": "PT24H",
            "reversal_horizon": "P30D",
            "reversal_rules": [
              {
                "key": "reopened",
                "event_name": "conversation.reopened",
                "action": "reverse",
                "condition": {
                  "property": "csat",
                  "operator": "eq",
                  "value": "2"
                },
                "applies_to": "any",
                "reason_code": "not_resolved"
              }
            ],
            "dispute_settings": {
              "decision_window": "P7D",
              "default_decision": "reverse"
            },
            "metadata": {}
          }
        ],
        "plans": [
          {
            "key": "enterprise_monthly",
            "name": "Enterprise",
            "billing_mode": "prepaid",
            "currency": "usd",
            "interval": "month",
            "rates": [
              {
                "event_name": "agent.task",
                "outcome_definition": "chat_resolution",
                "credits_per_unit": "10",
                "unit_amount_decimal": "95",
                "price_rule": "video_cost_plus",
                "included_quantity": "1000",
                "overage_unit_amount_decimal": "120",
                "burn_multiplier": "1",
                "description": "Chat resolutions"
              }
            ],
            "description": "string",
            "credit_type": "string",
            "recurring_fee": {
              "amount": 1500,
              "currency": "usd"
            },
            "included_credits": {
              "amount": "5000",
              "pool": "included",
              "rollover": "none",
              "rollover_cap": "2000"
            },
            "top_up": {
              "unit_amount_decimal": "1",
              "minimum_credits": "1000",
              "maximum_credits": "1000000",
              "pool": "purchased",
              "credits_expire_in": "P1Y",
              "low_balance_at": "1000",
              "auto": {
                "allowed": false,
                "maximum_monthly_limit": {
                  "amount": 1500,
                  "currency": "usd"
                }
              }
            },
            "allowances": [
              {
                "key": "weekly",
                "kind": "refill",
                "amount": "1500",
                "window": {
                  "type": "fixed",
                  "duration": "P1W",
                  "anchor": "billing_period"
                },
                "pool": "included",
                "scope": "customer",
                "rollover": "none",
                "rollover_cap": "500",
                "rollover_expires_after": "P1M",
                "priority": 50,
                "on_exhausted": "block",
                "alert_at": [
                  "0.8",
                  "1"
                ]
              }
            ],
            "pools": [
              {
                "key": "included",
                "name": "Included usage",
                "burn_multiplier": "1"
              }
            ],
            "per_seat": true,
            "default_spend_limit": {
              "amount": {
                "amount": 1500,
                "currency": "usd"
              },
              "ceiling": {
                "amount": 1500,
                "currency": "usd"
              },
              "period": {
                "duration": "P1M",
                "anchor": "calendar"
              },
              "counts": "paid_usage",
              "action": "warn",
              "alert_at": [
                "0.75",
                "0.9",
                "1"
              ]
            },
            "overdraft_limit": "0",
            "credit_limit": {
              "amount": 1500,
              "currency": "usd"
            },
            "minimum_commitment": {
              "amount": 1500,
              "currency": "usd"
            },
            "invoice_grace_period": "PT1H",
            "metadata": {}
          }
        ],
        "webhook_endpoints": [
          {
            "url": "https://api.example.com/webhooks/runledger",
            "enabled_events": [
              "outcome_charge.reversed",
              "dispute.decision_due",
              "invoice.finalized"
            ],
            "description": "string",
            "metadata": {}
          }
        ],
        "routing_rules": [
          {
            "provider": "adyen",
            "when": {
              "currency": "aud",
              "billing_country": "AU",
              "plan": "string",
              "mode": "top_up"
            },
            "position": 1
          }
        ],
        "notification_rules": [
          {
            "event": "dispute.decision_due",
            "channel": "email",
            "recipients": [
              "string"
            ],
            "webhook_endpoint": "we_4tJ9nR2cVx",
            "lead_time": "PT24H",
            "threshold": {
              "rate": "0.005",
              "credits_at_risk": {
                "credit_type": "ai_credits",
                "amount": "50000"
              }
            },
            "payment_provider": "string"
          }
        ],
        "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
          }
        ],
        "spend_limits": [
          {
            "amount": {
              "amount": 1500,
              "currency": "usd"
            },
            "ceiling": {
              "amount": 1500,
              "currency": "usd"
            },
            "counts": "paid_usage",
            "action": "warn",
            "alert_at": [
              "0.75",
              "0.9",
              "1"
            ],
            "enabled": true,
            "key": "team_monthly_cap",
            "applies_to": {
              "customer": "string",
              "plan": "string",
              "agent_id": "string",
              "member_id": "string",
              "team_id": "string",
              "pool": "string"
            },
            "period": {
              "duration": "P1M",
              "anchor": "calendar"
            },
            "set_by": "operator"
          }
        ],
        "account_settings": {
          "grant_expiry_notice": "P7D",
          "customer_view_branding": {
            "name": "Acme Support",
            "logo_url": "https://app.example.com/logo.png",
            "accent_color": "#17614f"
          }
        }
      },
      "changes": [
        {
          "path": "outcome_definitions.chat_resolution.confirmation_window",
          "before": null,
          "after": null
        }
      ],
      "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"
        }
      ],
      "proposed_by": {
        "type": "user",
        "id": "usr_4tN8vB2cXk",
        "name": "Claude Code",
        "on_behalf_of": "usr_4tN8vB2cXk",
        "client": "claude-code"
      },
      "review_url": "string",
      "expires_at": "2024-01-15T09:30:00Z",
      "livemode": true,
      "created_at": "2024-01-15T09:30:00Z",
      "reason": "string",
      "base_hash": "string",
      "decided_by": {
        "type": "user",
        "id": "usr_4tN8vB2cXk",
        "name": "Claude Code",
        "on_behalf_of": "usr_4tN8vB2cXk",
        "client": "claude-code"
      },
      "decision_note": "string",
      "decided_at": "2024-01-15T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "string"
}

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 proposals with this status.

Allowed values:

proposed_by_typeenumOptional

Only proposals from this kind of actor.

Allowed values:

created_afterdatetimeOptional

Only objects created at or after this time.

created_beforedatetimeOptional

Only objects created before this time.

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 proposals.

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