# Sessions

> Sessions let you lease a worker for stateful, multi-call interactions.

**URL:** https://inference.sh/docs/concepts/sessions
**Last updated:** 2026-09-18

---

Sessions let you lease a worker for stateful, multi-call interactions.

---

## What's a Session?

Normally, each task runs on whatever worker is available. The worker might change between calls, and state doesn't persist.

A **session** locks a specific worker to you:

```
Regular calls:              Sessions:

Task 1 → Worker A          Task 1 ┐
Task 2 → Worker B           ↓      │
Task 3 → Worker A          Task 2 ├→ Worker A (leased)
                            ↓      │
                           Task 3 ┘
```

With sessions:
- **Same worker** handles all your calls
- **State persists** in memory between calls
- **Faster responses** — no cold starts after the first call

---

## Session Lifecycle

```
┌─────────┐     ┌─────────┐     ┌─────────┐
│ Create  │ ──▶ │ Active  │ ──▶ │  Ended  │
└─────────┘     └─────────┘     └─────────┘
                    │
                    ▼
               ┌─────────┐
               │ Expired │
               └─────────┘
```

1. **Create** — Request `session: "new"` to start a session
2. **Active** — Worker is leased to you; make calls with the session ID
3. **Ended** — You explicitly end the session, or...
4. **Expired** — Session times out after idle period (default: 60 seconds, customizable 1s-1h)

---

## When to Use Sessions

### Use Sessions When

| Scenario | Example |
|----------|---------|
| **Stateful interactions** | Browser automation, code interpreters |
| **Multi-step operations** | Load data → Process → Export |
| **Interactive workflows** | User provides input between steps |
| **Accumulated state** | Conversation history, running calculations |

### Use Regular Calls When

| Scenario | Example |
|----------|---------|
| **Stateless operations** | Image generation, text completion |
| **Single requests** | One-off API calls |
| **Maximum throughput** | High-volume batch processing |

---

## How It Works

### Starting a Session

Pass `session: "new"` to create a session:

```python
result = client.run({
    "app": "my-app",
    "input": {...},
    "session": "new"  # Start new session
})

session_id = result["session_id"]  # e.g., "sess_abc123"
```

### Custom Session Timeout

By default, sessions expire after 60 seconds of inactivity. Customize this with `session_timeout` (1-3600 seconds):

```python
# Create a session with 5-minute idle timeout
result = client.run({
    "app": "my-app",
    "input": {...},
    "session": "new",
    "session_timeout": 300  # 5 minutes
})
```

Each successful call resets the idle timer. See [Sessions Developer Guide](/docs/extend/sessions) for full details.

### Continuing a Session

Use the session ID for subsequent calls:

```python
result = client.run({
    "app": "my-app",
    "input": {...},
    "session": session_id  # Use existing session
})
```

### Ending a Session

Explicitly end when done (releases the worker):

```python
client.sessions.end(session_id)
```

Or let it expire automatically after the idle timeout.

---

## Multi-Function Apps

Sessions work with any app, including multi-function apps. Call different functions within the same session:

```python
# Start session
result = client.run({
    "app": "browser-app",
    "function": "navigate",
    "input": {"url": "https://example.com"},
    "session": "new"
})
session_id = result["session_id"]

# Continue with different function
result = client.run({
    "app": "browser-app",
    "function": "click",
    "input": {"selector": "#login"},
    "session": session_id
})

# Another function
result = client.run({
    "app": "browser-app",
    "function": "screenshot",
    "input": {},
    "session": session_id
})
```

---

## Next

- [Sessions Developer Guide](/docs/extend/sessions) — Full API reference
- [Stateful Sessions Examples](/docs/examples/stateful-sessions) — Practical patterns