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

# List requests

> Retrieve a paginated list of your API requests with optional filtering and cost summary

Returns a paginated list of API requests for your organization, sorted newest first.

<Info>
  This endpoint uses the native Lumenfall API path (`/v1/requests`), not the OpenAI-compatible prefix (`/openai/v1`).
</Info>

## Query parameters

<ParamField query="limit" type="integer" default="20">
  Number of results to return per page. Minimum 1, maximum 100.
</ParamField>

<ParamField query="starting_after" type="string">
  Cursor for forward pagination. Returns results older than the request with this ID.
  Use the `next_page_url` from a previous response instead of constructing this manually.
</ParamField>

<ParamField query="ending_before" type="string">
  Cursor for backward pagination. Returns results newer than the request with this ID.
  Cannot be combined with `starting_after`.
</ParamField>

<ParamField query="created_after" type="string">
  Filter to requests created at or after this time. ISO 8601 datetime (e.g., `2026-03-01T00:00:00Z`).
</ParamField>

<ParamField query="created_before" type="string">
  Filter to requests created at or before this time. ISO 8601 datetime (e.g., `2026-03-31T23:59:59Z`).
</ParamField>

<ParamField query="key_id" type="string">
  Filter to requests made with a specific API key ID. You can retrieve your key IDs from the [List API keys](/api-reference/keys/list) endpoint.
</ParamField>

<ParamField query="summary" type="boolean">
  When `true`, includes a `summary` object with the total cost and count of all matching requests (not just the current page).
</ParamField>

## Response

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

<ResponseField name="data" type="array">
  Array of request objects, sorted newest first.

  <Expandable title="Request object">
    <ResponseField name="id" type="string">
      Unique request identifier (e.g., `req_2m4jLFHhkN1i4VrVHpjJqCOKlPw`).
    </ResponseField>

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

    <ResponseField name="created_at" type="string">
      When the request started, as an ISO 8601 datetime.
    </ResponseField>

    <ResponseField name="model" type="string | null">
      The model used (e.g., `flux-pro`, `gpt-image-1.5`).
    </ResponseField>

    <ResponseField name="modality" type="string | null">
      The request modality - `image`, `video`, `speech`, or `vision`.
    </ResponseField>

    <ResponseField name="endpoint" type="string | null">
      The API endpoint path (e.g., `/openai/v1/images/generations`).
    </ResponseField>

    <ResponseField name="status" type="string">
      Request status - `completed`, `pending`, `processing`, `upstream_failure`, `rejected`, or `cancelled`.
    </ResponseField>

    <ResponseField name="cost" type="number">
      Request cost in USD (e.g., `0.045`).
    </ResponseField>

    <ResponseField name="currency" type="string">
      Always `usd`.
    </ResponseField>

    <ResponseField name="duration_ms" type="integer | null">
      Total response time in milliseconds.
    </ResponseField>

    <ResponseField name="key_id" type="string | null">
      The API key ID used for this request.
    </ResponseField>

    <ResponseField name="error_code" type="string | null">
      Error code if the request failed (e.g., `ALL_PROVIDERS_EXHAUSTED`).
    </ResponseField>

    <ResponseField name="error_message" type="string | null">
      Human-readable error message if the request failed.
    </ResponseField>

    <ResponseField name="session_id" type="string | null">
      Caller-provided session ID for grouping related requests.
    </ResponseField>

    <ResponseField name="trace_id" type="string | null">
      Trace ID extracted from the W3C `traceparent` header.
    </ResponseField>

    <ResponseField name="user" type="string | null">
      End user identifier from the request body.
    </ResponseField>

    <ResponseField name="request_size_bytes" type="integer | null">
      Size of the request body in bytes.
    </ResponseField>

    <ResponseField name="response_size_bytes" type="integer | null">
      Size of the response body in bytes.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="next_page_url" type="string | null">
  URL to fetch the next page of results. `null` when there are no more results.
  Includes all original filters so you can follow it directly.
</ResponseField>

<ResponseField name="previous_page_url" type="string | null">
  URL to fetch the previous page of results. `null` when on the first page.
</ResponseField>

<ResponseField name="summary" type="object">
  Only present when `summary=true`. Aggregates across all matching requests, not just the current page.

  <Expandable title="Summary object">
    <ResponseField name="total_cost" type="number">
      Total cost of all matching requests in USD.
    </ResponseField>

    <ResponseField name="currency" type="string">
      Always `usd`.
    </ResponseField>

    <ResponseField name="count" type="integer">
      Total number of matching requests.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.lumenfall.ai/v1/requests?limit=5" \
    -H "Authorization: Bearer $LUMENFALL_API_KEY"
  ```

  ```bash cURL (with filters) theme={null}
  curl "https://api.lumenfall.ai/v1/requests?created_after=2026-03-01T00:00:00Z&created_before=2026-03-31T23:59:59Z&summary=true" \
    -H "Authorization: Bearer $LUMENFALL_API_KEY"
  ```

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

  response = requests.get(
      "https://api.lumenfall.ai/v1/requests",
      headers={"Authorization": "Bearer your-lumenfall-api-key"},
      params={
          "limit": 5,
          "created_after": "2026-03-01T00:00:00Z",
          "summary": "true",
      },
  )
  data = response.json()

  for req in data["data"]:
      print(f"{req['created_at']} {req['model']} ${req['cost']}")

  # Paginate
  while data["next_page_url"]:
      response = requests.get(
          f"https://api.lumenfall.ai{data['next_page_url']}",
          headers={"Authorization": "Bearer your-lumenfall-api-key"},
      )
      data = response.json()
      for req in data["data"]:
          print(f"{req['created_at']} {req['model']} ${req['cost']}")
  ```

  ```typescript TypeScript theme={null}
  const baseUrl = "https://api.lumenfall.ai";
  const headers = { Authorization: "Bearer your-lumenfall-api-key" };

  let url: string | null = `${baseUrl}/v1/requests?limit=5&summary=true`;

  while (url) {
    const response = await fetch(url, { headers });
    const data = await response.json();

    for (const req of data.data) {
      console.log(`${req.created_at} ${req.model} $${req.cost}`);
    }

    url = data.next_page_url ? `${baseUrl}${data.next_page_url}` : null;
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "object": "list",
    "data": [
      {
        "id": "req_2m4jLFHhkN1i4VrVHpjJqCOKlPw",
        "object": "request",
        "created_at": "2026-03-15T14:32:10.000Z",
        "model": "flux-pro",
        "modality": "image",
        "endpoint": "/openai/v1/images/generations",
        "status": "completed",
        "cost": 0.045,
        "currency": "usd",
        "duration_ms": 2340,
        "key_id": "test_abc123",
        "error_code": null,
        "error_message": null,
        "session_id": null,
        "trace_id": null,
        "user": null,
        "request_size_bytes": 1024,
        "response_size_bytes": 524288
      },
      {
        "id": "req_2m4jKEGfmR8h3UqTGnhHpBNkMOx",
        "object": "request",
        "created_at": "2026-03-15T14:30:05.000Z",
        "model": "gpt-image-1.5",
        "modality": "image",
        "endpoint": "/openai/v1/images/generations",
        "status": "completed",
        "cost": 0.02,
        "currency": "usd",
        "duration_ms": 4120,
        "key_id": "test_abc123",
        "error_code": null,
        "error_message": null,
        "session_id": null,
        "trace_id": null,
        "user": null,
        "request_size_bytes": 512,
        "response_size_bytes": 1048576
      }
    ],
    "next_page_url": "/v1/requests?starting_after=req_2m4jKEGfmR8h3UqTGnhHpBNkMOx&limit=5",
    "previous_page_url": null
  }
  ```

  ```json With summary theme={null}
  {
    "object": "list",
    "data": [
      {
        "id": "req_2m4jLFHhkN1i4VrVHpjJqCOKlPw",
        "object": "request",
        "created_at": "2026-03-15T14:32:10.000Z",
        "model": "flux-pro",
        "modality": "image",
        "endpoint": "/openai/v1/images/generations",
        "status": "completed",
        "cost": 0.045,
        "currency": "usd",
        "duration_ms": 2340,
        "key_id": "test_abc123",
        "error_code": null,
        "error_message": null,
        "session_id": null,
        "trace_id": null,
        "user": null,
        "request_size_bytes": 1024,
        "response_size_bytes": 524288
      }
    ],
    "next_page_url": "/v1/requests?starting_after=req_2m4jLFHhkN1i4VrVHpjJqCOKlPw&limit=20&summary=true",
    "previous_page_url": null,
    "summary": {
      "total_cost": 12.34,
      "currency": "usd",
      "count": 347
    }
  }
  ```
</ResponseExample>