> Index of every page on this site: [llms.txt](https://docs.a-line.cloud/llms.txt)

# Logs

> The logs operations of the v1 API.

## Read a build's log by line

`GET /v1/clusters/{cluster_id}/apps/{app_id}/builds/{build_id}/logs` (operation ID `get_build_logs`)

Cursor paginated: pass `next_cursor` back as `cursor` until it is null. While the build runs, `has_more` stays true and the cursor can be polled for new lines. Build log lines carry no timestamps.

Authentication: `api_key` ([how to authenticate](/api/authentication)).

**Parameters**

- `cursor` (query, `string`): `next_cursor` of the previous page.
- `limit` (query, `integer`): Lines per page, 1 to 5000 (default 500).
- `cluster_id` (path, required, `string`): The cluster UUID
- `app_id` (path, required, `string`): The application UUID
- `build_id` (path, required, `string`): The build UUID

**Responses**

- `200`: A page of build log lines. Body: [`V1BuildLogsPage`](/api/reference/schemas#v1buildlogspage).
- `400`: Invalid limit.
- `401`: Missing, invalid or revoked API key.
- `403`: The key's scope does not allow this.
- `404`: Cluster, application or build not found.
- `422`: Unknown or malformed query parameter or cursor.
- `429`: This API key spent its request budget for the current window (code `rate_limited`); retry after `Retry-After` seconds. Body: [`V1Error`](/api/reference/schemas#v1error).

```bash
curl 'https://api.a-line.cloud/v1/clusters/00000000-0000-4000-8000-000000000001/apps/00000000-0000-4000-8000-000000000002/builds/00000000-0000-4000-8000-000000000003/logs' \
  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key'
```

## Query an app's container logs over a time range, oldest first

`GET /v1/clusters/{cluster_id}/apps/{app_id}/logs` (operation ID `get_app_logs`)

Cursor paginated: pass `next_cursor` back as `cursor`, with the same `since` and `until`, until `has_more` is false. Lines are kept for the cluster's log retention. There is no live tail on this API.

Authentication: `api_key` ([how to authenticate](/api/authentication)).

**Parameters**

- `cursor` (query, `string`): `next_cursor` of the previous page.
- `limit` (query, `integer`): Lines per page, 1 to 1000 (default 100).
- `pod` (query, `string`): Only lines of this pod.
- `since` (query, `string`): Start of the range (RFC 3339, inclusive). Default: an hour before `until`.
- `until` (query, `string`): End of the range (RFC 3339, exclusive). Default: now. Pass it when paging, so every page reads the same range. At most 31 days after `since`.
- `cluster_id` (path, required, `string`): The cluster UUID
- `app_id` (path, required, `string`): The application UUID

**Responses**

- `200`: A page of log lines. Body: [`V1AppLogsPage`](/api/reference/schemas#v1applogspage).
- `400`: Invalid range or limit.
- `401`: Missing, invalid or revoked API key.
- `403`: The key's scope does not allow this.
- `404`: Cluster or application not found.
- `422`: Unknown or malformed query parameter or cursor.
- `429`: This API key spent its request budget for the current window (code `rate_limited`); retry after `Retry-After` seconds. Body: [`V1Error`](/api/reference/schemas#v1error).

```bash
curl 'https://api.a-line.cloud/v1/clusters/00000000-0000-4000-8000-000000000001/apps/00000000-0000-4000-8000-000000000002/logs' \
  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key'
```
