Retrieve an event

GET

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

GET

/v1/events/:event_id

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

{
  "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
  }
}

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

event_idstringRequired

The event ID (ev_...).

Response

The event.

idstring

object"event"

idempotency_keystring

namestring

The event name as recorded. It never changes after the event is recorded.

kindenum

What the event turned out to be. usage: charged at once. outcome: created a pending outcome charge. signal: evaluated against reversal rules. unpriced: stored with no effect.

Allowed values:

customerstring

timestampdatetime

quantitystring

effectsobject

The IDs of everything the event created or changed.

warningslist of objects

livemodeboolean

created_atdatetime

referencestringOptional

agent_idstringOptional

member_idstringOptional

team_idstringOptional

run_idstringOptional

propertiesmap from strings to anyOptional

evidenceobjectOptional

What shows an outcome happened, stamped on the outcome charge. Keep it short and factual; it is shown to people deciding disputes. Free text is sanitized before it reaches dashboards or agent tools.

pricingobjectOptional

How a price rule priced a usage event. Left out for other events.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

429

Too Many Requests Error

500

Internal Server Error