How Clous cursor pagination works, the stable set of error codes, and rate-limit behavior.

Pagination, Errors & Rate limits

Cursor pagination

Clous uses cursor pagination everywhere. There is no offset parameter and no 10,000-result ceiling — you can page through an entire result set deterministically.

Each response carries a page object:

{
  "page": {
    "limit": 25,
    "next_cursor": "eyJvIjoyNX0",
    "has_more": true
  }
}

Field	Meaning
`limit`	The page size that was applied (1–100, default 25).
`next_cursor`	Opaque token for the next page, or `null` on the last page.
`has_more`	`true` when another page exists.

To fetch the next page, pass next_cursor back as the cursor query parameter:

curl -s "https://api.clous.ai/v1/advisers?state=NY&cursor=eyJvIjoyNX0" \
  -H "Authorization: Bearer clous_live_..."

import requests

cursor = None
while True:
    params = {"state": "NY", "limit": 100}
    if cursor:
        params["cursor"] = cursor
    body = requests.get(
        "https://api.clous.ai/v1/advisers",
        headers={"Authorization": "Bearer clous_live_..."},
        params=params,
        timeout=30,
    ).json()

    for adviser in body["data"]:
        ...  # process

    if not body["page"]["has_more"]:
        break
    cursor = body["page"]["next_cursor"]

Cursors are opaque — don't parse or construct them. Always read next_cursor from the response and pass it back verbatim.

Error codes

Errors are explicit and drawn from a small, stable set, so agents can branch on them reliably:

Code	When it happens
`empty_result`	The query was valid but matched no records. Surfaced via `warnings`; the response still returns `200` with `data: []`.
`entity_unresolved`	An identifier could not be resolved to a canonical entity.
`not_found`	A specific resource (e.g. a CRD) does not exist.
`invalid_param`	A parameter was the wrong type, malformed, or out of range. Returned as HTTP `422`.
`rate_limited`	The request was throttled or the account's credit balance is exhausted.

A validation error (invalid_param) follows the OpenAPI 422 shape:

{
  "detail": [
    {
      "loc": ["query", "aum_min"],
      "msg": "Input should be greater than or equal to 0",
      "type": "greater_than_equal"
    }
  ]
}

Requests may be throttled to protect the service; throttled requests return the rate_limited error. Usage is also governed by your credit balance — when credits are exhausted, calls stop rather than silently incurring charges. Monitor usage and adjust your plan from the dashboard; see Credits & Pricing.

Best practices:

Back off and retry on rate_limited with exponential backoff.
Prefer larger limit values (up to 100) and cursor pagination over many small requests.
Treat empty_result as a normal outcome, not an error to retry.

Pagination, Errors & Rate limits

Pagination, Errors & Rate limits

Cursor pagination

Error codes

Rate limits

On this page