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

# List Request Logs

> List API request logs for the organization

<Note>
  **Beta.** The request logs schema is new and may evolve. Field names should be stable, but we reserve the right to add fields or adjust response shape before general availability.
</Note>

## Overview

Returns a paginated list of API request logs for the authenticated organization. Filterable by date range, HTTP status code, success/failure outcome, method, API key, endpoint type, and path. Per-plan access control limits the historical window:

| Plan                        | Retention window |
| --------------------------- | ---------------- |
| `free`                      | Last 7 days      |
| `starter`                   | Last 30 days     |
| `beta`, `pro`, `enterprise` | Last 90 days     |

Requires the `billing:read` scope. Querying logs does not consume metered usage.

## Query Parameters

<ParamField query="start_date" type="string">
  Start of date range (ISO 8601). Accepts `YYYY-MM-DD` or full ISO datetime. Defaults to 24 hours ago.
</ParamField>

<ParamField query="end_date" type="string">
  End of date range (ISO 8601). Accepts `YYYY-MM-DD` or full ISO datetime. Defaults to now.
</ParamField>

<ParamField query="from" type="string">
  Alias for `start_date`. If both are sent, `start_date` wins.
</ParamField>

<ParamField query="to" type="string">
  Alias for `end_date`. If both are sent, `end_date` wins.
</ParamField>

<ParamField query="status_code" type="integer">
  Filter to a specific HTTP status code (100--599).
</ParamField>

<ParamField query="success" type="boolean">
  Filter by outcome: `true` returns succeeded requests (status `< 400`), `false` returns failed requests (status `>= 400`).
</ParamField>

<ParamField query="method" type="string">
  Filter by HTTP method (`GET`, `POST`, `PATCH`, `DELETE`, etc.).
</ParamField>

<ParamField query="api_key_id" type="string">
  Filter to requests made with a specific API key (`key_...`).
</ParamField>

<ParamField query="endpoint_type" type="string">
  Filter by classified endpoint type. One of `search`, `read`, `monitoring`, `screening`, `clearance`, `check`, `image_search`, `export`, `reference`, `utility`.
</ParamField>

<ParamField query="search" type="string">
  Case-insensitive substring match against path or request ID (max 200 characters).
</ParamField>

<ParamField query="limit" type="integer" default="50">
  Items per page (1--100).
</ParamField>

<ParamField query="cursor" type="string">
  Pagination cursor from a previous response.
</ParamField>

## Response

<ResponseField name="object" type="string">Always `"list"`.</ResponseField>

<ResponseField name="data" type="object[]">
  <Expandable title="Request log object">
    <ResponseField name="id" type="string">The logged request's identifier (`req_...`).</ResponseField>
    <ResponseField name="object" type="string">Always `"request_log"`.</ResponseField>
    <ResponseField name="method" type="string">HTTP method (`GET`, `POST`, etc.).</ResponseField>
    <ResponseField name="path" type="string">Request path (e.g. `/v1/trademarks`).</ResponseField>
    <ResponseField name="status_code" type="integer">HTTP status code returned.</ResponseField>
    <ResponseField name="duration_ms" type="integer">Request duration in milliseconds.</ResponseField>
    <ResponseField name="endpoint_type" type="string">Classified endpoint type (e.g. `search`, `read`, `utility`).</ResponseField>
    <ResponseField name="credits" type="integer">Credits charged against your plan for this request.</ResponseField>
    <ResponseField name="api_key_prefix" type="string">Prefix of the API key used (null if the request predates prefix capture).</ResponseField>
    <ResponseField name="error_type" type="string">Error type slug (null on success).</ResponseField>
    <ResponseField name="error_detail" type="string">Error detail message (null on success).</ResponseField>
    <ResponseField name="created_at" type="string">ISO timestamp when the request was logged.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="has_more" type="boolean">Whether more pages are available.</ResponseField>

<ResponseField name="pagination" type="object">
  <Expandable title="Pagination">
    <ResponseField name="cursor" type="string">Cursor for the next page (null if this is the last page).</ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json theme={null}
  {
    "object": "list",
    "data": [
      {
        "id": "req_01HXYZ...",
        "object": "request_log",
        "method": "GET",
        "path": "/v1/trademarks",
        "status_code": 200,
        "duration_ms": 142,
        "endpoint_type": "search",
        "credits": 1,
        "api_key_prefix": "sig_7kMn",
        "error_type": null,
        "error_detail": null,
        "created_at": "2026-04-18T10:12:33Z"
      },
      {
        "id": "req_01HXYA...",
        "object": "request_log",
        "method": "GET",
        "path": "/v1/trademarks/tm_bogus",
        "status_code": 404,
        "duration_ms": 18,
        "endpoint_type": "read",
        "credits": 0,
        "api_key_prefix": "sig_7kMn",
        "error_type": "not_found",
        "error_detail": "Trademark tm_bogus does not exist.",
        "created_at": "2026-04-18T10:11:05Z"
      }
    ],
    "has_more": true,
    "pagination": {
      "cursor": "eyJpZCI6I..."
    },
    "request_id": "req_currentCall"
  }
  ```
</ResponseExample>

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.signa.so/v1/organization/logs?limit=50&status_code=429" \
    -H "Authorization: Bearer sig_xxxxxxxxxxxx"
  ```

  ```typescript TypeScript theme={null}
  import { Signa } from "@signa-so/sdk";

  const signa = new Signa({ api_key: "sig_xxxxxxxxxxxx" });

  const logs = await signa.organization.logs.list({
    start_date: "2026-04-17",
    end_date: "2026-04-18",
    status_code: 429,
    limit: 50,
  });
  ```

  ```python Python theme={null}
  import requests

  resp = requests.get(
      "https://api.signa.so/v1/organization/logs",
      headers={"Authorization": "Bearer sig_xxxxxxxxxxxx"},
      params={"status_code": 429, "limit": 50},
  )
  logs = resp.json()["data"]
  ```
</CodeGroup>

## Errors

| Status | Type                  | Description                                        |
| ------ | --------------------- | -------------------------------------------------- |
| 400    | `validation_error`    | Invalid date format or `start_date > end_date`     |
| 401    | `unauthorized`        | Missing or invalid API key                         |
| 403    | `forbidden`           | API key lacks `billing:read`                       |
| 403    | `plan_limit_exceeded` | Requested window exceeds your plan's log retention |
| 429    | `rate_limited`        | Too many requests                                  |

## Related Endpoints

* [Get Request Log](/api-reference/administration/get-log) -- single request log detail
* [Get Usage Summary](/api-reference/administration/get-usage-summary) -- aggregate usage by day, endpoint type, or API key