> ## 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.

# Get a request

> Retrieve a single API request by ID

Returns a single request from your organization by its ID. The request object matches one element of the [List requests](/api-reference/requests/list) endpoint's `data` array.

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

## Path parameters

<ParamField path="request_id" type="string" required>
  The ID of the request to retrieve (e.g., `req_2m4jLFHhkN1i4VrVHpjJqCOKlPw`).
</ParamField>

## Response

<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>

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

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

  response = requests.get(
      "https://api.lumenfall.ai/v1/requests/req_2m4jLFHhkN1i4VrVHpjJqCOKlPw",
      headers={"Authorization": "Bearer your-lumenfall-api-key"},
  )
  req = response.json()
  print(f"{req['created_at']} {req['model']} {req['status']} ${req['cost']}")
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch(
    "https://api.lumenfall.ai/v1/requests/req_2m4jLFHhkN1i4VrVHpjJqCOKlPw",
    { headers: { Authorization: "Bearer your-lumenfall-api-key" } }
  );
  const req = await response.json();
  console.log(`${req.created_at} ${req.model} ${req.status} $${req.cost}`);
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "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
  }
  ```
</ResponseExample>