> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kordless.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Request logs

> Inspect API request history, status, and request IDs.

Every request to the `/v1` API is logged — success or failure. Each response includes an `x-request-id` header that you can use to find the request later. Request logs record metadata only — never secrets, payloads, or results.

## What a request log contains

```json theme={null}
{
  "request_id": "req_abc123",
  "object": "request_log",
  "method": "POST",
  "path": "/v1/accounts/acct_abc123/quotes",
  "status": 201,
  "environment": "test",
  "acting_account_id": "acct_abc123",
  "target_account_id": "acct_abc123",
  "billing_account_id": "acct_abc123",
  "account_connection_id": null,
  "error_code": null,
  "duration_ms": 142,
  "created_at": "2026-07-29T12:00:00Z"
}
```

| Field                   | Description                                                                         |
| ----------------------- | ----------------------------------------------------------------------------------- |
| `request_id`            | The unique identifier for this request. Matches the `x-request-id` response header. |
| `method`                | The HTTP method (`GET`, `POST`).                                                    |
| `path`                  | The request path, truncated to 300 characters.                                      |
| `status`                | The HTTP status code returned.                                                      |
| `environment`           | The environment the key belongs to (`test` or `live`).                              |
| `acting_account_id`     | The account that owns the API key.                                                  |
| `target_account_id`     | The account the request targeted (may differ for connected accounts).               |
| `billing_account_id`    | The account responsible for billing on this request.                                |
| `account_connection_id` | The connection ID, if the target was a connected account.                           |
| `error_code`            | The error code, if the request failed. `null` on success.                           |
| `duration_ms`           | How long the request took to process, in milliseconds.                              |
| `created_at`            | When the request was received, in ISO 8601 format.                                  |

## What request logs do not contain

* No request bodies or response bodies.
* No API key secrets or hashes.
* No customer information.
* No simulation results (simulations are non-persistent by design).

## Endpoints

### List request logs

```bash theme={null}
curl -s "https://your-kordless-instance.com/v1/logs?limit=10&status=201" \
  -H "Authorization: Bearer sk_test_..." | jq .
```

Returns a list of request logs, newest first, scoped to your account and environment.

#### Query parameters

| Parameter | Type    | Default | Description                                 |
| --------- | ------- | ------- | ------------------------------------------- |
| `limit`   | integer | 50      | Number of logs to return. Clamped to 1–200. |
| `status`  | integer | —       | Filter by exact HTTP status code (100–599). |
| `path`    | string  | —       | Filter by exact request path.               |

### Get a single request log

```bash theme={null}
curl -s "https://your-kordless-instance.com/v1/logs/req_abc123" \
  -H "Authorization: Bearer sk_test_..." | jq .
```

Returns the request log for a specific `request_id`. The ID is scoped to your account and environment — an unknown or foreign ID returns `404` with `request_log_not_found`.

## Scoping

Request logs are scoped to the authenticated key's account and environment:

* A Test key sees only Test-environment logs.
* A Live key sees only Live-environment logs.
* A key from account A cannot see logs from account B.

This means the `logs:read` scope grants access to your own traffic only — never to another account's traffic.

## In the workspace

The Developers page also shows request logs in the human console. Unlike the API (which is scoped to one environment), the console can search across both Test and Live environments, and can filter by request ID, status, and path.

## Using request logs

Request logs are useful for:

* **Debugging** — Find a failed request by its `x-request-id` and see the error code and timing.
* **Monitoring** — Track API usage patterns and error rates.
* **Support** — When contacting support, include the `request_id` so the team can find the exact request.

## Logs never fail the response

The request log is written in a `finally` block after the response is sent. If the log write fails (for example, a database issue), the API response is not affected — the customer still gets their quote or simulation. The log failure is recorded in server-side error output.

For the full request log schema, see the [API reference](/api-reference/openapi).