---
title: "Requests, pagination and limits"
description: "Build predictable AI Glot API clients using response envelopes, strict parameters, cursor pagination, request IDs, rate limits and retries."
canonical: "https://ai-glot.com/docs/api/conventions"
updated: "2026-08-09"
---

# Requests, pagination and limits

## JSON envelopes

Successful single-resource responses use:

```json
{ "data": {}, "request_id": "req_example" }
```

Lists add pagination fields:

```json
{
  "data": [],
  "has_more": true,
  "next_cursor": "opaque-cursor",
  "request_id": "req_example"
}
```

Unknown query fields and JSON properties are rejected. This catches typos instead of silently ignoring a filter or write.

## Defaults

Defaults are chosen for safe interactive use. For example, usage defaults to the last 30 days and translations default to 25 recent, non-archived records. A requested list limit above 100 is clamped to 100.

Dates and timestamps use ISO 8601. JSON field names are `snake_case`. Fields that are not yet applicable are usually `null` so resource shapes stay stable across a translation lifecycle.

## Cursor pagination

Pass `next_cursor` from one response into the next request unchanged. Stop when it is `null` or `has_more` is false.

```js title="List every translation"
let cursor;
do {
  const url = new URL('https://api.ai-glot.com/v1/batches');
  url.searchParams.set('limit', '100');
  if (cursor) url.searchParams.set('cursor', cursor);

  const page = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.AIGLOT_API_KEY}` },
  }).then(response => response.json());

  for (const translation of page.data) console.log(translation.id);
  cursor = page.next_cursor;
} while (cursor);
```

Do not construct or modify cursors. Cursor pagination prevents a newly created translation from shifting rows between pages.

## Rate limits

Each credential has a sustained limit of **240 requests per minute** and a burst ceiling of **40 requests per 10 seconds**. A `429` response includes `Retry-After`; wait for it before retrying.

## Request IDs and retries

Every response carries a request ID in both the payload and `Request-Id` header. Include it when asking for support.

Retry `429`, `500`, `502`, `503` and `504` with exponential backoff and jitter. Do not retry validation, authentication, permission or not-found errors without changing the request.

Trailing slashes are tolerated. The REST API intentionally sends no browser CORS permission because workspace credentials belong in trusted server-side code.