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

> ## Agent Instructions
> Start with the plan page, https://docs.scrip.dev/agents.md. It covers connecting, configuring, integrating, verifying, and operating a Scrip program.
> Events are asynchronous. `POST /v1/events` returns 202 when the event is accepted. Rules run afterward, so wait for the `event.completed` webhook or poll `GET /v1/events/{id}` before you read balances.
> Send the participant's `external_id` with an event. The first event for a new `external_id` enrolls the participant, so do not create participants first.
> The hosted MCP server is https://mcp.scrip.dev/mcp. It uses OAuth and is read-only. Make changes through the REST API or the dashboard.
> Add `.md` to any docs URL to get the page as Markdown. Request and response schemas are in https://docs.scrip.dev/openapi.json.

# Limits and durations

> Page sizes, request sizes, rate-limit guidance, and the duration format

This page lists the limits that apply across the API. Other pages link here instead of repeating them.

## Rate limits

Requests are rate-limited per organization. All API keys in an organization share one limit, and each API instance enforces its own ceiling. Build to this guidance:

| Limit | Value | Meaning |
| - | - | - |
| Sustained rate | 10 requests/second | Steady throughput the API allows continuously |
| Burst | 30 requests | Maximum requests allowed in a short spike before throttling |

When you exceed the limit, the API returns `429` with the code `rate_limit_exceeded` and a `Retry-After` header. Every response carries these headers:

| Header | Description |
| - | - |
| `X-RateLimit-Limit` | The ceiling of the instance that served your request |
| `X-RateLimit-Remaining` | Requests remaining in the current window |
| `X-RateLimit-Reset` | Unix timestamp (seconds) when the bucket is fully replenished |
| `Retry-After` | Seconds to wait before retrying (only on `429` responses) |

For higher throughput, [contact us](mailto:support@scrip.dev) about enterprise rate limits.

## Sizes and counts

| Limit | Value |
| - | - |
| List page size | `limit` defaults to 50 and has a maximum of 200. A larger value returns `400` with reason `out_of_range` |
| Request body | 1 MiB. A larger body returns `413` with `request_too_large` |
| Events per batch | 100 on `POST /v1/events/batch` |
| Recipients per transfer | 100 |
| Assets per lookup by ID | 500 |
| `Idempotency-Key` header | 1 to 255 printable ASCII characters |
| Numbers in `event_data` | Up to 2^53. Send larger values as strings |

## Retries

A transient event failure retries automatically up to 5 times, after 2, 4, 8, 16, and 32 seconds. A validation failure is terminal. See [Event processing](/guides/event-processing).

Your webhook endpoint can slow delivery with a `429` response and a `Retry-After` header. Scrip honors values up to 1 hour. See [Webhooks](/guides/webhooks).

## Durations

Fields that take a duration accept a number followed by a unit. You can combine units, as in `1w2d12h`.

| Unit | Meaning |
| - | - |
| `s` | Seconds |
| `m` | Minutes. `m` never means months |
| `h` | Hours |
| `d` | Days of 24 hours |
| `w` | Weeks of 7 days |

`30d` and `720h` are equivalent. A pending redemption deadline accepts 60 seconds through 365 days. See [Redemption lifecycle](/guides/redemption-lifecycle).

Timestamps are RFC 3339, for example `2026-10-11T10:30:00Z`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.