> 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.

# List jobs

GET https://api.tillcast.com/v1/jobs

Jobs, newest first. With `printer` (an id) the list is that printer's; add
`status=pending` for the jobs waiting for it, oldest first. Without
`printer` the list covers every printer. `customer` and `location` (ids)
narrow it to the jobs made for that customer or that location: the ones a
job was queued for, and not where its printer is now. A location in another
customer than the one named holds none of its jobs. With `printer` they
have to match where the printer is now, or the list is empty. With
`client_reference_id` the list holds every job that carries that value (it
is not unique, so many can), newest first, narrowed by the ones you name; an
unknown value is an empty list, and `status` cannot be combined with it. A
customer, a location or a printer that is not yours is `404`. Jobs are kept
for 7 days after they end.
A search reads only so many rows in one request: it may answer fewer
than `limit` objects, even none, with `has_more` true and a
`next_cursor`, which you send as `starting_after` (or `ending_before`)
to go on until `has_more` is false.

**Scope:** `jobs:read`.

Reference: https://docs.tillcast.com/api-reference/jobs/list

## Authentication

- `Authorization` header (bearer token, required) — A restricted API key, `tc_rk_live_` and 32 characters. Send it as `Authorization: Bearer <key>`. A key lists its scopes, and each operation below names the one it needs; a key may also be limited to one customer. An owner or a developer of the organization makes a key in the dashboard, under API keys, after a code sent to their e-mail. The key is shown once, when it is made. An owner or a developer can revoke it there, and a revoked key stops working within a minute.

## Request

### Query parameters

- `limit` (integer, optional) — How many objects a page holds, 1 to 100. The default is 10.
- `starting_after` (string, optional) — The id of the last object of the page you hold: returns the page that follows it. In a search by `client_reference_id` the answer can be a short page, or none, with `has_more` true and a `next_cursor`: send that instead, and go on until `has_more` is false.
- `ending_before` (string, optional) — The id of the first object of the page you hold: returns the page that precedes it. Not together with `starting_after`. In a search by `client_reference_id` read backward, the `next_cursor` of the answer when it has one.
- `printer` (string, optional) — Only this printer's jobs: its id.
- `status` (string, optional) — `pending`: only the jobs waiting for the printer, oldest first. Needs `printer`; not with `client_reference_id`.
- `customer` (string, optional) — Only the jobs made for this customer: its id.
- `location` (string, optional) — Only the jobs made for this location: its id.
- `client_reference_id` (string, optional) — Only the jobs that carry this client reference id (1 to 128 characters). It is not unique, so the list can hold many; an unknown value is an empty list.

## Response

### 200

A page of jobs.

- `data` (list of JobObject, required)
- `has_more` (boolean, required) — Whether another page follows. Ask for it with `starting_after` set to the id of the last object here, or, when the answer has a `next_cursor`, with that. A search by `client_reference_id` can answer a short page, or none, with `has_more` true: it reads only so many rows in one request, and `next_cursor` is the way on.
- `object` (string, required) — Always `list`.
- `next_cursor` (string, optional) — Only in the answer to a search (`client_reference_id`) that stopped before it could fill the page: it read all the rows it may in one request. Then `data` holds what it found so far, possibly nothing, `has_more` is true, and this is the position to continue from: pass it as `starting_after` (or as `ending_before`, if you page backward) in place of the id of the last object. It is an id of the kind of the list, but not necessarily the id of an object in `data`. Left out otherwise.

## Errors

### 400 Bad Request Error

The request is malformed or a parameter is invalid.

- `error` (ErrorObject, required)

### 401 Unauthorized Error

The key (or token) is missing or not valid.

- `error` (ErrorObject, required)

### 403 Forbidden Error

Not allowed.

- `error` (ErrorObject, required)

### 404 Not Found Error

There is no such object, or it is another organization's.

- `error` (ErrorObject, required)

### 500 Internal Server Error

A problem on Tillcast's side.

- `error` (ErrorObject, required)

## Types

### JobObject

A print job.

- `client_reference_id` (string, required, nullable) — The id of this job in your own system, such as an order number, or `null`. Not unique: the same value can be on many jobs, and `GET /v1/jobs?client_reference_id=` lists every job that carries it (the last 7 days). No personal data.
- `completed_at` (string, required, nullable)
- `created_at` (string, required)
- `customer` (string, required)
- `delivered_at` (string, required, nullable)
- `expires_at` (string, required) — When the job stops being offered to the printer.
- `id` (string, required)
- `kind` (string, required) — `api` (yours), `welcome` (the first-connection receipt) or `test` (a test print: never billed).
- `location` (string, required)
- `metadata` (map from string to string, required, nullable)
- `object` (string, required)
- `printer` (string, required)
- `profile` (string, required, nullable) — The profile the document was rendered for: the id of a preset (`x-tillcast-profiles` lists them). A plain string and not an enum, so that a profile that is retired never breaks a client. `null` for a job that was queued as ready printer data and not rendered from a document, such as every job from before documents were rendered.
- `reason` (string, required, nullable) — Why the job did not print.
- `result_code` (string, required, nullable) — The printer's own status code for the job.
- `size_bytes` (long, required) — The size in bytes of what the printer is sent: the rendered document, after the transport step. Not the size of the document you sent.
- `status` (string, required) — `queued`, `delivered`, `printed`, `failed`, `expired` or `cancelled`.
- `transport` (string, required, nullable) — The transport step applied to the rendered bytes: its id and revision, such as `cloudprnt-star.1`. A later correction of a step changes new jobs only, and this tells which jobs were rendered with which. `null` where `profile` is.
- `warnings` (list of DocumentWarning, required) — What the renderer noticed in the document, in the order it happened: at most 21 (the first 20, and a `too_many_warnings` that says there were more). Always there, an empty list for a document with nothing to say. Kept with the job: a replay of the request and every later read return the same list.

### ErrorObject

- `code` (string, required) — A stable code to branch on. The ones known today are listed in `x-codes` of this schema; a new one can be added, so a client treats a code it does not know by the HTTP status.
- `message` (string, required) — A sentence for a person. Do not parse it.
- `param` (string, required, nullable) — The request parameter the error is about, if one.
- `request_id` (string, required) — Quote it when you ask for help.
- `type` (string, required) — The kind of error: `invalid_request_error`, `authentication_error`, `permission_error`, `conflict_error`, `idempotency_error`, `rate_limit_error` or `api_error`.

### DocumentWarning

Where the renderer did something other than the document says. A warning never changes what the renderer would print; it tells where it fell back quietly (a line with a stray brace is dropped, a column is made narrower, a character the printer cannot print becomes `?`). The message is a fixed text per code: it holds no part of the document, so it is safe to show or log.

- `code` (string, required) — A stable code to branch on. The ones known today are listed in `x-codes` of this schema; a new one can be added, so a client treats a code it does not know as a warning in general.
- `column` (integer, required, nullable) — The column on that line, from 1, counted in Unicode characters of the document (normalised to NFC); `null` when the document was rewritten at that place and the position cannot be told.
- `line` (integer, required) — The line of the document, from 1.
- `message` (string, required) — A sentence for a person. Do not parse it.

## Examples

**Response**

```json
{
  "data": [
    {
      "client_reference_id": "Invoice 2026/10/0815",
      "completed_at": null,
      "created_at": "2026-10-11T10:00:00Z",
      "customer": "cus_c3x9k2m3",
      "delivered_at": null,
      "expires_at": "2026-10-11T11:00:00Z",
      "id": "job_01M466JX008T2V5X7Z9C1E3G5H",
      "kind": "api",
      "location": "loc_01M42YMFP03Q1P9N7M5K3H1G0F",
      "metadata": {
        "booking": "4711"
      },
      "object": "job",
      "printer": "prn_01M44X7TQ0A9R2H5J8K1M4N7P0",
      "profile": "star-starprnt-utf8-80mm",
      "reason": null,
      "result_code": null,
      "size_bytes": 1194,
      "status": "queued",
      "transport": "cloudprnt-star.1",
      "warnings": [
        {
          "code": "line_dropped_stray_brace",
          "column": 5,
          "line": 3,
          "message": "The line contains a stray brace and prints nothing."
        }
      ]
    }
  ],
  "has_more": false,
  "object": "list"
}
```

**SDK Code**

```python
import requests

url = "https://api.tillcast.com/v1/jobs"

querystring = {"client_reference_id":"order-1042","customer":"cus_c3x9k2m3","limit":"25","location":"loc_01M42YMFP03Q1P9N7M5K3H1G0F","printer":"prn_01M44X7TQ0A9R2H5J8K1M4N7P0","starting_after":"cus_c3x9k2m3","status":"pending"}

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

```javascript
const url = 'https://api.tillcast.com/v1/jobs?client_reference_id=order-1042&customer=cus_c3x9k2m3&limit=25&location=loc_01M42YMFP03Q1P9N7M5K3H1G0F&printer=prn_01M44X7TQ0A9R2H5J8K1M4N7P0&starting_after=cus_c3x9k2m3&status=pending';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.tillcast.com/v1/jobs?client_reference_id=order-1042&customer=cus_c3x9k2m3&limit=25&location=loc_01M42YMFP03Q1P9N7M5K3H1G0F&printer=prn_01M44X7TQ0A9R2H5J8K1M4N7P0&starting_after=cus_c3x9k2m3&status=pending"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.tillcast.com/v1/jobs?client_reference_id=order-1042&customer=cus_c3x9k2m3&limit=25&location=loc_01M42YMFP03Q1P9N7M5K3H1G0F&printer=prn_01M44X7TQ0A9R2H5J8K1M4N7P0&starting_after=cus_c3x9k2m3&status=pending")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.tillcast.com/v1/jobs?client_reference_id=order-1042&customer=cus_c3x9k2m3&limit=25&location=loc_01M42YMFP03Q1P9N7M5K3H1G0F&printer=prn_01M44X7TQ0A9R2H5J8K1M4N7P0&starting_after=cus_c3x9k2m3&status=pending")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.tillcast.com/v1/jobs?client_reference_id=order-1042&customer=cus_c3x9k2m3&limit=25&location=loc_01M42YMFP03Q1P9N7M5K3H1G0F&printer=prn_01M44X7TQ0A9R2H5J8K1M4N7P0&starting_after=cus_c3x9k2m3&status=pending', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.tillcast.com/v1/jobs?client_reference_id=order-1042&customer=cus_c3x9k2m3&limit=25&location=loc_01M42YMFP03Q1P9N7M5K3H1G0F&printer=prn_01M44X7TQ0A9R2H5J8K1M4N7P0&starting_after=cus_c3x9k2m3&status=pending");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.tillcast.com/v1/jobs?client_reference_id=order-1042&customer=cus_c3x9k2m3&limit=25&location=loc_01M42YMFP03Q1P9N7M5K3H1G0F&printer=prn_01M44X7TQ0A9R2H5J8K1M4N7P0&starting_after=cus_c3x9k2m3&status=pending")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```