---
title: "List agent logs"
method: GET
path: "/v1/projects/{project_id}/logs"
tags: ["stats"]
---

# List agent logs

`GET /v1/projects/{project_id}/logs`

## Request

- Base URL: `https://api.connic.co`
- URL: `https://api.connic.co/v1/projects/{project_id}/logs`
- Auth: HTTP bearer

Cursor-paginated feed of the log lines agents wrote during runs in one environment (trace entries of type `log`). Pass `next_cursor` back as `cursor` to load the next page in the same `direction`. To fetch logs written after the first page, pass its `first_cursor` with `direction=newer`. Time filters apply to the log timestamp and take the same values as `GET /runs`.

Required permission: `logs.view`.

## Path parameters

- `project_id` string, uuid, required

## Query parameters

- `environment_id` string, uuid, required: Environment to list logs from
- `time_range` '1h' | '6h' | '24h' | '7d' | '30d' | 'today' | 'this_month' | 'last_month' | 'this_year', nullable: Preset window ending now, or a calendar period in UTC. Ignored when both `start_date` and `end_date` are set.
- `start_date` string, date-time, nullable: Custom window start; applies only together with `end_date` and overrides `time_range`.
- `end_date` string, date-time, nullable: Custom window end; applies only together with `start_date`.
- `deployment_id` string, uuid, nullable: Filter by deployment
- `exclude_test_runs` boolean: Exclude logs from runs with a test name
- `agent_name` string[], nullable: Filter by one or more agent names
- `level` string[], nullable: Filter by one or more log levels
- `source` string[], nullable: Filter by one or more log sources
- `search` string, nullable: Match log message, source, or agent name
- `cursor` string, nullable: Opaque cursor returned by the previous logs response
- `direction` 'older' | 'newer': `older` returns logs before `cursor`, newest first; `newer` returns logs after `cursor`, oldest first.
- `limit` integer: Page size, 1 to 250.

## Response `200`

Successful Response

- PublicProjectLogsResponse
  - `logs` PublicProjectLogItemResponse[], required: Log entries, newest first for `direction=older` and oldest first for `direction=newer`.
    - `id` string, uuid, required
    - `run_id` string, uuid, required: Run that wrote the log entry.
    - `deployment_id` string, uuid, nullable, required: Deployment that ran the agent. Null when none is recorded.
    - `agent_name` string, required: Agent that wrote the log entry.
    - `run_status` 'scheduled' | 'queued' | 'started' | 'awaiting_approval' | 'completed' | 'failed' | 'cancelled' | 'blocked', required: Run state: `scheduled` until its start time, `queued`, `started` while executing, `awaiting_approval` while paused for a human decision, then `completed`, `failed` or `cancelled`.
    - `trace_name` string, required: Source of the entry: `log:system`, or `log:tool:`, `log:middleware:`, `log:hook:` or `log:guardrail:` followed by a name.
    - `level` string, required: Log level, such as `debug`, `info`, `warning` or `error`.
    - `message` string, required: Log text, up to 2,048 characters, with secret values masked.
    - `timestamp` string, date-time, nullable, required: When the entry was written.
    - `queued_at` string, date-time, nullable, required: When the run entered the queue.
    - `test_name` string, nullable, required: A/B test variant that handled the run. Null for the base agent.
  - `has_more` boolean, required: Whether more entries exist beyond this page in the same direction.
  - `next_cursor` string, nullable, required: Pass as `cursor` with the same `direction` to load the next page. Null when `has_more` is false.
  - `first_cursor` string, nullable, required: Cursor of the first entry on this page. Pass it with `direction=newer` to load entries written after this page.
  - `last_cursor` string, nullable, required: Cursor of the last entry on this page. Null when the page is empty.
  - `direction` 'older' | 'newer', required: Paging direction used: `older` pages back in time, `newer` pages forward.

## Other responses

- `401`: Missing or invalid API key.
- `403`: The API key lacks the required permission or access to the environment.
- `422`: Validation Error
- `429`: Rate limit exceeded.

---

[API](https://skmtc.dev/connic/apis/connic-api.md) · [All operations](https://skmtc.dev/connic/apis/connic-api/llms.txt) · [OpenAPI document](https://skmtc.dev/connic/apis/connic-api/revisions/482932da5fbe?raw)