---
title: Configure Agent Analytics session timeouts
description: "Override the 30-minute idle timeout for Agent Analytics sessions with the AI SDK or the HTTP API, and check whether sessions closed explicitly or by timeout."
product: general
lang: en
token_estimate: 929
---
# Configure Agent Analytics session timeouts

> For AI agents: a documentation index is available at [/docs/llms.txt](/docs/llms.txt). Append `.md` to any page URL for markdown, or send `Accept: text/markdown`.

By default, Agent Analytics closes a session after 30 minutes without agent events, and caps any session at 24 hours. Override the idle timeout per session when your jobs have long natural gaps, such as support tickets that wait on a human, so a pause doesn't close the session before the work is done.

Choose the value first. [Idle timeout values](https://amplitude.com/docs/amplitude-ai/agent-analytics/sessions#idle-timeout-values) describes what `30`, larger values, and `-1` do, and the tradeoff of setting the timeout too low or too high. Where possible, close sessions explicitly instead of relying on the timeout.

## Set the override with the AI SDK

Set `idleTimeoutMinutes` (Node) or `idle_timeout_minutes` (Python) when you open the session, and also add an `idle_timeout_minutes` key to the agent's `context`. The server reads the `context` key even for sessions that never close explicitly, so setting both makes sure the override takes effect.

#### Node

```typescript
const agent = ai.agent('support-bot', {
  context: { idle_timeout_minutes: 240 },   // read even without an explicit close
});
const session = agent.session({
  userId,
  sessionId: ticketId,
  idleTimeoutMinutes: 240,                  // the session-level parameter
});
```

#### Python

```python
agent = ai.agent(
    "support-bot",
    context={"idle_timeout_minutes": 240},   # read even without an explicit close
)
session = agent.session(
    user_id=user_id,
    session_id=ticket_id,
    idle_timeout_minutes=240,                # the session-level parameter
)
```

## Set the override without the AI SDK

Add an `idle_timeout_minutes` key to the `[Agent] Context` JSON on any event in the session. The first value wins, and the server reads it even for sessions that never receive a Session End. If you send a Session End, also set `[Agent] Session Idle Timeout Minutes` on it to the same value.

```javascript
amplitude.track('[Agent] User Message', {
  '[Agent] Session ID': ticketId,
  '[Agent] Turn ID': 1,
  '[Agent] Trace ID': traceId,
  '[Agent] Agent ID': 'support-bot',
  '[Agent] Message ID': messageId,
  '[Agent] Context': JSON.stringify({ idle_timeout_minutes: 240 }),
  $llm_message: { text: redactedText },
});

// When the ticket resolves:
amplitude.track('[Agent] Session End', {
  '[Agent] Session ID': ticketId,
  '[Agent] Agent ID': 'support-bot',
  '[Agent] Session Idle Timeout Minutes': 240,
});
```

Don't build your own short idle timer. Rotating session IDs after a few quiet minutes splits one conversation into several sessions: enrichment judges partial conversations, task completion looks artificially low, and because billing is per agent session, one conversation bills as several. If your product defines sessions by inactivity, set a matching `[Agent] Session Idle Timeout Minutes` and keep the window generous. Refer to [Should I build my own client-side idle timer to end sessions?](https://amplitude.com/docs/amplitude-ai/agent-analytics/faq#should-i-build-my-own-client-side-idle-timer-to-end-sessions) in the FAQ.

## Check how sessions closed

Every `[Agent] Session Record` carries `[Agent] Close Reason`, either `explicit_close` or `timeout`. Chart Session Records grouped by Close Reason to see how often the idle timeout closes your sessions. A high share of `timeout` on jobs with a known end can mean your code isn't sending Session End. Refer to [Troubleshoot Agent Analytics setup](https://amplitude.com/docs/amplitude-ai/agent-analytics/troubleshooting).