Headers, pages and the rate limit of a request

Overview states the conventions every operation follows. This page adds what a request may carry besides its body and what an answer carries back, how a list longer than one page is read, and how many requests a key may send.

Headers

On the answers to an API key, Retry-After comes with the 429 of the rate limit (below), with a 503 that has the code pool_exhausted when the provider asked its last attempt to wait, and with the refusal of a change of a budget that waited too long for the calls in flight on it.

A list, page by page

A list that is read page by page answers one page at a time and adds meta to it: limit, the size of the page, and next_cursor.

curl "https://api.slen.ai/api/v1/ledger-entries?limit=2" \
  -H "Authorization: Bearer $SLEN_API_KEY"

{
  "data": [
    {
      "entry_id": "74442131708452864",
      "reservation_id": "74442097331195904",
      "type": "usage_capture",
      "amount": "0.00014100",
      "currency": "USD",
      "metadata": {
        "input_tokens": 420,
        "output_tokens": 130,
        "is_partial": false,
        "estimated_cost": "0.00018300",
        "reserved_amount": "0.00021960"
      },
      "created_at": "2026-10-02T08:40:15+00:00"
    },
    {
      "entry_id": "74442097335390208",
      "reservation_id": "74442097331195904",
      "type": "reservation_hold",
      "amount": "0.00021960",
      "currency": "USD",
      "metadata": {
        "model_code": "gpt-4o-mini",
        "estimation_strategy": "maximum",
        "safety_multiplier": "1.200"
      },
      "created_at": "2026-10-02T08:40:12+00:00"
    }
  ],
  "meta": {
    "limit": 2,
    "next_cursor": "74442097335390208"
  }
}

• limit sets the size of a page: from 1 to 100, 30 when you send none — 50 for the list of customers.

• To read the next page, send the same request again with cursor set to next_cursor of the page you have. Change nothing else, or the next page is a page of another list.

• next_cursor is null on the last page. A page that is exactly limit long still carries a cursor, so the end of a list can also be a page with an empty data and null.

• The cursor is a value to send back, not to build.

The lists of operations, of holds and of ledger entries read a window of time as well, at most seven days long. The page of each of those resources says how.

Four lists can also be read by the number of a page, with the count of their rows: the operations, the executions of a flow, the holds and the ledger entries. Send page instead of cursor, and meta carries page, limit, total and anchor instead of next_cursor — Search and numbered pages shows how.

The rate limit

A key may send 120 requests a minute, unless the service is set up otherwise. The minute starts with the first request of the key. Every request the limit lets through counts, one answered with an error too. A person signed in to the console has a limit of their own. The probes /health and /ready are not counted.

Every answer carries two headers of the limit: the limit itself and what is left of it — the answer below shows them after Retry-After. A request over the limit is not carried out. It is answered with 429 and the code rate_limit_exceeded, with Retry-After — the seconds until the minute ends — and with the moment it ends, in Unix seconds.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 17
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1790932877
X-Request-Id: 3f6c1a52-8f0e-4c1b-9a57-1d2e6b7c9f10

{"error":{"code":"rate_limit_exceeded","message":"API rate limit exceeded","request_id":"3f6c1a52-8f0e-4c1b-9a57-1d2e6b7c9f10"}}

Wait as long as Retry-After says, then send the request again. One operation has a smaller limit besides: the check of a provider connection, POST /v1/provider-connections/{id}/test, may be sent six times a minute.

Where to go next

• Overview — the base address, the shape of an answer and of an error, how values are written.

• Idempotency — which operations require a key, and what a repeat is answered with.

• Error codes — every code of the API, what it means and what to do about it.