Track events in a batch

POST

https://api.runledger.co/v1/events/batch

POST

/v1/events/batch

curl -X POST https://api.runledger.co/v1/events/batch \
     -H "Authorization: Bearer <api_key>" \
     -H "Content-Type: application/json" \
     -d '{
  "events": [
    {
      "idempotency_key": "conv_4821-resolved",
      "name": "resolution.chat"
    }
  ]
}'

{
  "object": "string",
  "results": [
    {
      "idempotency_key": "string",
      "status": "created",
      "event": {
        "id": "ev_3mN8xQ2pLc",
        "object": "string",
        "idempotency_key": "string",
        "name": "resolution.chat",
        "kind": "usage",
        "customer": "string",
        "timestamp": "2024-01-15T09:30:00Z",
        "quantity": "1",
        "effects": {
          "ledger_entries": [
            "string"
          ],
          "reversals": [
            "string"
          ],
          "disputes": [
            "string"
          ],
          "hold": "string",
          "outcome_charge": "string"
        },
        "warnings": [
          {
            "code": "no_rate_for_event",
            "message": "string"
          }
        ],
        "livemode": true,
        "created_at": "2024-01-15T09:30:00Z",
        "reference": "string",
        "agent_id": "string",
        "member_id": "string",
        "team_id": "string",
        "run_id": "string",
        "properties": {},
        "evidence": {
          "description": "Customer confirmed the refund arrived and closed the chat.",
          "url": "https://app.example.com/conversations/conv_4821",
          "properties": {}
        },
        "pricing": {
          "price_rule": "video_cost_plus",
          "price_rule_version": 1,
          "method": "cost_plus",
          "price": "134.4",
          "basis": "catalog",
          "lines": [
            {
              "unit": "string",
              "quantity": "string",
              "dimensions": {},
              "cost_model": "cm_6bR3xN8vQe",
              "rate_card": "rc_4tG9wK2nPd",
              "rate_card_version": 1,
              "rate_source": "catalog",
              "override": "textco_negotiated",
              "catalog_price": "catp_9cW4hL6rBv",
              "cost": {
                "amount_decimal": "0.042",
                "currency": "usd"
              }
            }
          ],
          "cost": "96",
          "floor_applied": true,
          "cap_applied": true
        }
      },
      "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"
      }
    }
  ]
}

Records up to 100 events in one request. Each event succeeds or fails on its own; the batch is not atomic. Results come back in request order.

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.

Request

This endpoint expects an object.

eventslist of objectsRequired

Response

One result per submitted event.

object"event_batch"

resultslist of objects

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

409

Conflict Error

422

Unprocessable Entity Error

429

Too Many Requests Error

500

Internal Server Error