{
  "schema_version": 2,
  "id": "develop/ai/context-engine/lens/limits",
  "title": "Lens limits and errors",
  "url": "https://redis.io/docs/latest/develop/ai/context-engine/lens/limits/",
  "summary": "Lens request limits, how the SDK exports turns, error responses, and troubleshooting.",
  "tags": [
    "docs",
    "develop",
    "ai"
  ],
  "last_updated": "2026-11-03T15:51:18-08:00",
  "page_type": "content",
  "content_hash": "bd069db271a16dfdc48a843863c1f9f805d9e885e2ecb2457c5e22644ca00a9e",
  "sections": [
    {
      "id": "overview",
      "title": "Overview",
      "role": "overview",
      "text": "Check these limits when you design IDs and read large sessions, and use the error tables to handle failed requests."
    },
    {
      "id": "request-limits",
      "title": "Request limits",
      "role": "content",
      "text": "| Limit | Value |\n| ----- | ----- |\n| Session, thread, user, and agent IDs | Up to 256 bytes each. The software development kit (SDK) shortens longer IDs and logs a warning. |\n| Results per retrieval step | Up to 100. The fetched count keeps the true total. |\n| Ingest request size | Up to 8 mebibytes (MiB) by default. |\n| Sessions per page | Up to 200. Default 50. |\n| Sessions per listed range | Up to 10,000. Narrow the range or add filters to list more. |\n| Turns per session read | Up to 10,000. |\n\nYour administrator can change the ingest request size and sets the retention windows. See [self-managed retention](https://redis.io/docs/latest/operate/iris/lens/self-managed/configuration#retention)."
    },
    {
      "id": "how-lens-exports",
      "title": "How Lens exports",
      "role": "content",
      "text": "The SDK exports turns in the background, so your agent doesn't wait on Lens:\n\n- Each export has a 10-second deadline.\n- The SDK retries rate limits, timeouts, server errors, and connection errors within that deadline. A rate-limited export waits for the server's `Retry-After` value, up to 30 seconds.\n- When an export fails, the SDK logs a warning on the `iris.lens` logger and keeps running. Export errors never raise into your agent.\n\nTo see the SDK's warnings, configure Python `logging` to show `WARNING` messages, for example with `logging.basicConfig(level=logging.WARNING)`."
    },
    {
      "id": "ingest-errors",
      "title": "Ingest errors",
      "role": "content",
      "text": "The ingest endpoint returns these statuses. The SDK names `401`, `403`, `413`, and `429` in its warnings:\n\n| Status | Meaning | Action |\n| ------ | ------- | ------ |\n| `400` | The export body isn't a valid OpenTelemetry request. | Export with the Redis Iris SDK. |\n| `401` | The ingest key is missing or invalid. | Check `IRIS_LENS_API_KEY`. |\n| `403` | The key can't ingest for this instance. | Use a key with the `ingest` or `full` scope. |\n| `413` | The export exceeds the ingest request size. | Set `OTEL_BSP_MAX_EXPORT_BATCH_SIZE` below 64 to send smaller batches, or turn content capture off. |\n| `429` | The instance is at capacity. | The SDK retries. Sustained `429` responses mean the instance needs more capacity. |\n| `503` | Ingest is unavailable or not enabled for this instance. | The SDK retries. If it persists, ask your administrator to check that ingest is enabled. |"
    },
    {
      "id": "read-errors",
      "title": "Read errors",
      "role": "content",
      "text": "Read application programming interface (API) errors return a problem details body with a `type` and a `title`:\n\n| Status | `type` | Action |\n| ------ | ------ | ------ |\n| `400` | `/errors/invalid-data` | Correct the request parameters. The body lists each invalid field. |\n| `401` | `/errors/authentication-failed` | Check `LENS_API_KEY`. |\n| `403` | `/errors/insufficient-permissions` | Use a key with the `read` or `full` scope. |\n| `404` | `/errors/resource-not-found` | Check the ID. A new turn becomes readable a few seconds after export. |\n| `500` | `/errors/unexpected-error` | Retry the request. |\n| `503` | `/errors/service-unavailable` | Retry after a short wait. |"
    },
    {
      "id": "troubleshoot-a-missing-turn",
      "title": "Troubleshoot a missing turn",
      "role": "errors",
      "text": "If a turn doesn't appear in Lens, check these in order:\n\n1. **Lens is configured.** `IRIS_LENS_ENDPOINT` is set in the process, and `IRIS_LENS_ENABLED` isn't `false`. `lens.init()` returns `True` when both are true. With no endpoint, every Lens call does nothing.\n1. **The turn has an agent ID.** Set `IRIS_LENS_AGENT_ID`, pass `agent_id` to `lens.init()`, or pass it to `lens.turn()`. Lens groups every turn by agent.\n1. **The turn has a session ID.** Pass `session_id` to `lens.turn()`. The Lens UI shows only turns that have one.\n1. **The export succeeded.** A short-lived process calls `lens.shutdown()` before it exits. Check the `iris.lens` warnings for a failed export, such as a rejected key.\n1. **The endpoint uses Transport Layer Security (TLS).** Lens refuses an `http://` endpoint that isn't a loopback address. See [Connect over TLS](https://redis.io/docs/latest/develop/ai/context-engine/lens/configure#connect-over-tls).\n1. **You're looking in the right place.** Select the agent ID the turn used, and a time range that includes it."
    },
    {
      "id": "troubleshoot-missing-steps",
      "title": "Troubleshoot missing steps",
      "role": "errors",
      "text": "| Symptom | Check |\n| ------- | ----- |\n| Model calls don't appear in the turn. | Install `redis-iris[llm-tracing]` and call `lens.init()` at startup. Lens traces the OpenAI, Anthropic, Amazon Bedrock, and LangChain clients. |\n| A source shows `not-instrumented`. | Record prompt assembly, and pass `fetched()` and `used()` the same items, with their text, that you recorded as results. |\n| Iris service calls don't appear. | Make the calls inside `lens.turn()`, through the service objects such as `AgentMemory`, not their generated `.client`. |"
    }
  ],
  "examples": []
}