> For the complete documentation index, see [llms.txt](https://docs.contextual.io/documentation-and-resources/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/logs-api.md).

# Logs API

Search your tenant's execution log messages and read log sessions from code.

The Logs API reads your tenant's execution logs: the log messages that Agents, Actions, and Triggers write, and the log sessions that group them. The Console's log views use it, and the CLI's `ctxl logs` command uses it to search stored log messages. `ctxl logs --follow` instead shows new messages as they arrive, through the [Notifications API](https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/notifications-api.md). Use the Logs API from scripts and tools that need log data outside the Console. For example, a support script can find recent `error` messages and then read the other messages from the same session.

To search logs in the Console, see [Logs](https://docs.contextual.io/documentation-and-resources/tenants/monitoring/logs.md).

## What you can do

* Search log messages by level, time range, session, or other fields, or with a [Contextual Log Query Language (CLQL)](https://docs.contextual.io/documentation-and-resources/tenants/tenant-logs/contextual-log-query-language-clql.md) query.
* List log sessions and read one session. A session groups the messages from one run, such as one execution of an Action.
* Check the logs backlog, which is the number of log messages waiting to be stored. Administrators can also clear the backlog. Clearing it discards the waiting messages: they are never stored, so you can't search them. Not every tenant supports clearing. In a tenant that doesn't, the request returns `405`.

The reference also lists operations that write and flush log sessions. Contextual services use the write operations to record logs from Agents, Actions, and Triggers.

The [Observability API](https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/observability-api.md) reference also lists `POST /logs`. That operation is not implemented and returns `501`. Use the Logs API to read logs.

## Base URL and reference

* **API base URL:** `https://logs.<tenant-id>.my.contextual.io/api/v1`
* **Swagger reference:** [Logs API reference](https://logs.prod-001.prod.contextual.io/api-docs/)
* **Raw OpenAPI:** [openapi.json](https://logs.prod-001.prod.contextual.io/api-docs/openapi.json)

Replace `<tenant-id>` with the [tenant ID from your Tenant Workspace URL](https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/authentication-and-permissions.md#identify-the-tenant). On the API base URL, the hostname identifies your tenant, so the `x-org-id` header is optional. If you send it, its value must match the hostname.

The OpenAPI document uses the relative server `/api/v1`. When you import it into an API client or AI tool, set the server to the API base URL.

## Authentication and permissions

See [Authentication and Permissions](https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/authentication-and-permissions.md) for credential and token guidance. Send the access token in the `Authorization: Bearer <access-token>` header. A request without a valid token returns `401`.

The Console and the CLI call this API with the signed-in person's token. The default Owner, Admin, and Logs Viewer roles let people view logs in the Console.

The backlog operations check for a log permission. A caller without it gets `403`. In the default roles:

| Task                   | Default roles that allow it   |
| ---------------------- | ----------------------------- |
| View the logs backlog  | Owner, Admin, and Logs Viewer |
| Clear the logs backlog | Owner and Admin               |

Log messages can contain data that your solution processes. Give log access only to people and systems that need it.

## Request and response details

* `GET /logs` takes search parameters in the query string. `POST /$page/logs` takes the same parameters as top-level properties of a JSON body, with the same names, such as `"exactSearch.level"`. Use it for long CLQL queries.
* Filter log messages with these parameters:
  * `exactSearch.<field>`: one value or a comma-separated list. For example, `exactSearch.level=error,fatal`. Fields include `level`, `sessionId`, `source`, `kind` (`trigger`, `action`, or `execution`), and `subKind`.
  * `from.createdAt` and `to.createdAt`: the start (inclusive) and end (exclusive) of a time range. Use an ISO 8601 UTC time, such as `2026-10-27T00:00:00Z`, or a relative time, such as `now-24h`.
  * `search.query`: a [CLQL](https://docs.contextual.io/documentation-and-resources/tenants/tenant-logs/contextual-log-query-language-clql.md) query.
* Lists return results in `items`. To get the next page, send the response's `nextPageToken` as `pageToken`, with the same filters and `orderBy`. Continue until a response has no `nextPageToken`. A `nextPageToken` does not mean that more results exist: the next page can be empty.
* To page through log messages, set `orderBy` to `createdAt:desc` or `createdAt:asc`. Without a sort, a log search returns a `nextPageToken` only if the request also sets `includeTotal=true`.
* Send the filter parameters and `orderBy` unchanged. Use a plain HTTP request, as in the [example request](#example-request), or a client that supports these parameters.
* Each message in search results has an `id`, `createdAt`, `level` (`fatal`, `error`, `warn`, `info`, or `debug`), and `message`. It also has fields from the session that wrote it, such as `sessionId`, `source`, `kind`, and `typeId`. Fields such as `subKind` and `instanceId` appear only when the writer sets them. `message` is an object, and its content depends on the writer. Search results do not include a `_metaData` object.
* Searches return only messages within your tenant's log retention period. See [Logs](https://docs.contextual.io/documentation-and-resources/tenants/monitoring/logs.md).
* This API does not stream new messages. To watch logs as they arrive, use [Live Tail](https://docs.contextual.io/documentation-and-resources/tenants/monitoring/live-tail.md) in the Console.
* When you form a request, replace `[\$]` in a reference path with a literal `$`. For example, `/[\$]page/logs` becomes `/$page/logs`. In a shell command, put a URL that contains `$page` in single quotes, or write `\$page`, so that the shell doesn't replace `$page` with a variable's value.
* Requests can be rate limited for each caller. When a limit applies, responses include `RateLimit` and `RateLimit-Policy` headers, and a request over the limit returns `429`.

## Example request

This request gets up to 50 `error` and `fatal` messages from the past 24 hours, newest first:

```bash
curl --get "https://logs.<tenant-id>.my.contextual.io/api/v1/logs" \
  --header "Authorization: Bearer <access-token>" \
  --data-urlencode "exactSearch.level=error,fatal" \
  --data-urlencode "from.createdAt=now-24h" \
  --data-urlencode "orderBy=createdAt:desc" \
  --data-urlencode "pageSize=50"
```

Replace `<access-token>` with your access token. A successful response has status `200` and the matching messages in `items`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/logs-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
