> Tillcast is live: the API at https://api.tillcast.com/v1 and the dashboard at https://dashboard.tillcast.com. A key prints on real printers, so do not call the API unless asked. A job carries its receipt as "document", an array of blocks (the recommended way), or as "receiptline", ReceiptLine text, exactly one of the two: read https://docs.tillcast.com/create-a-print-job.md and https://docs.tillcast.com/concepts/documents.md before you write a job body. Do not code against what does not exist yet: webhooks, a template language, stored templates (a job has no template field), OAuth connections and connectors for Make, Zapier and n8n, and OAuth sign-in for the MCP server. SDKs for TypeScript (@tillcast/sdk, version 0.2.0 or later for blocks) and Python (tillcast) exist as pre-1.0 versions. To show a receipt in a web page without printing, there are the npm packages @tillcast/preview and @tillcast/html-render (0.x, no API key, no call to Tillcast to draw): read https://docs.tillcast.com/preview-a-receipt.md. The docs are the source of truth: check the index https://docs.tillcast.com/llms.txt and https://docs.tillcast.com/roadmap.md before you code against anything. For clean Markdown of any page, append .md to the page URL. The Tillcast MCP server is live at https://api.tillcast.com/mcp and takes an API key as a bearer token (setup: https://docs.tillcast.com/connect-an-ai-assistant.md). It acts on the live account and its tools print on real paper, so do not connect to it or call its tools unless the owner asked you to. The MCP server at https://docs.tillcast.com/_mcp/server is a different one: it only searches these docs and cannot call the Tillcast API.

# Rate limits and retention

> The limits of the Tillcast API, job limits and retention periods.

## Rate limits

Tillcast does not limit the number of requests per key today. The limits that exist protect a printer and the service from loops:

| Limit                        | Value                                    | Answer                                          |
| ---------------------------- | ---------------------------------------- | ----------------------------------------------- |
| Jobs waiting for one printer | 50                                       | `429 queue_full`, with a `Retry-After` header   |
| Test prints for one printer  | 5 in any minute, and 3 waiting at a time | `429 rate_limited`, with a `Retry-After` header |
| New organizations            | 3 per person, and 20 an hour in all      | `429 rate_limited`                              |

A limited request gets HTTP `429`. Wait for the number of seconds in `Retry-After`, then retry (`queue_full` sends 30). A queue empties as the printer prints, as you cancel jobs and as jobs pass their `expires_at` (24 hours by default), so do not retry `queue_full` in a loop. The SDKs wait for `Retry-After` inside the call, so one call can block for about a minute: see [Retry safely](/create-a-print-job#retry-safely). Handle `429` in your client now, so that a limit added later does not surprise you.

Be kind to the service even without a limit:

* Lists that span a whole organization, such as all printers, are slower than a list by location or by customer. Prefer a list by location, and do not sweep large lists every few seconds.
* Do not poll for job state faster than you need. A printer takes a job within about one poll interval, 5 seconds by default. Webhooks, which avoid polling, are planned and not built. See [Webhooks and events](/events/webhooks).

## Job limits

| Limit                            | Value                                                                                                                                                       |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Blocks (`document`)              | 1,000 blocks. Larger is `422 document_invalid`. The same receipt written in ReceiptLine can be 256 KB of UTF-8 text, and larger is `413 document_too_large` |
| ReceiptLine text (`receiptline`) | 256 KB of UTF-8 text. Larger is `413 document_too_large`                                                                                                    |
| What the document renders to     | 256 KB of printer data, and 90 KB for the profile `epson-legacy-80mm-42`. Larger is `413 rendered_too_large`                                                |
| Request body                     | 800 KB for creating a job, 400 KB for every other request. Larger is `413 request_too_large`                                                                |
| Waiting jobs per printer         | 50. When the queue is full, new jobs are refused with `429 queue_full`                                                                                      |
| Job lifetime                     | 24 hours by default. `expires_in` is 60 seconds to 7 days                                                                                                   |
| Warnings per job                 | 21: the first 20, and `too_many_warnings`                                                                                                                   |
| `client_reference_id`            | 1 to 128 characters                                                                                                                                         |
| `metadata`                       | 10 pairs, 1 KB in all                                                                                                                                       |
| `Idempotency-Key`                | 1 to 64 visible ASCII characters, remembered for 24 hours                                                                                                   |

See [Jobs](/concepts/jobs#job-limits) and [Receipt documents](/concepts/documents#limits-and-refusals).

## Retention

| Data                               | Kept                                                                                                                                                                                                                                                   |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Rendered receipt data              | Until the job is final. A job that never ends loses it from one hour after its `expires_at`, which is 7 days and one hour after the job is made at the latest, by a background clean-up that can be late. Tillcast does not keep the document you sent |
| Job state and outcome              | 7 days after the job is final, and from 7 days after `expires_at` for a job that never ends, by a background clean-up that can be late                                                                                                                 |
| Audit entries of dashboard actions | 90 days. They are written now, and there is no endpoint to read them yet                                                                                                                                                                               |

Some data does not exist yet, because the features that make it are planned: printer state events (3 months), lifecycle events (1 year), the webhook delivery log (30 days), and usage statistics. Their periods are decided. The full table is in [Security and data](/security#how-long-data-is-kept). There is no option to keep data longer, not even for a fee.