---
title: "Paging and limits"
description: "How list calls page with a cursor, the rate limit headers, and what each response carries."
---

> Documentation Index
> Fetch the complete documentation index at: https://tarkle.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Paging and limits

## Responses

Requests and responses are JSON, except `GET /brands/{brand}/markdown`, which returns `text/markdown`. Every response carries `X-Tarkle-Api-Version: v1` and is sent with `Cache-Control: no-store`.

Failures are [problem documents](/docs/api/errors) (`application/problem+json`). Branch on the `code` member.

## Paging

List calls such as `GET /brands`, `GET /brands/{brand}/requests` and `GET /files` return one page at a time and take `limit` and `cursor`.

- `limit` is a whole number: 1 to 100 for brand lists (default 25), 1 to 1,000 for `GET /files` (default 100). A value outside the range or one that is not a whole number answers `400`. Tarkle does not round it.
- Each page returns `next_cursor`. Send it back unchanged as `cursor` to get the next page. It is `null` on the last page, and there is no empty page after it.
- The cursor is opaque. It marks the place after the last row you saw, so rows added or removed between two calls are not skipped or repeated, and there is no limit on how deep you can page.
- A cursor that Tarkle did not issue answers `400 invalid_request` ("Invalid cursor").

## Rate limits

Limits are per token. Brand calls allow 120 requests a minute. Files calls and `GET /workspaces` allow 600 a minute. These are working values, so read the limit from the headers instead of hard-coding it.

Every authenticated response carries:

| Header | Meaning |
| --- | --- |
| `X-RateLimit-Limit` | Requests allowed per minute in this token's bucket. |
| `X-RateLimit-Remaining` | Requests left in the current minute. |
| `X-RateLimit-Reset` | When the current window ends, in Unix seconds. |

When a token goes over its limit the answer is [`429 rate_limited`](/docs/api/errors/rate_limited) with `Retry-After` in whole seconds, the exact time left in the window (never less than 1). Wait that long, then retry.

Only valid tokens are counted: a missing or invalid token answers `401` first. The limit runs before the scope check, so `403` answers count.

## Versions

The version is in the path (`/api/v1`). Inside v1 Tarkle only adds things, so ignore fields and error codes you do not know. A change that could break a client ships as a new version, and the old one keeps working for at least six months after its end is announced, with `Deprecation` and `Sunset` headers on its responses.

Source: https://tarkle.com/docs/api/paging-and-limits/index.mdx