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

# List Sessions

> List sessions for your organization

List all sessions for your organization. Supports filtering by status and phone.

## Request

```bash theme={null}
curl https://api.tapkit.ai/v1/sessions \
  -H "X-API-Key: joot_your_api_key"
```

### Query Parameters

| Parameter  | Type      | Default | Description                                                                        |
| ---------- | --------- | ------- | ---------------------------------------------------------------------------------- |
| `status`   | `string`  | —       | Filter by status: `creating`, `running`, `paused`, `completed`, `failed`, `killed` |
| `phone_id` | `string`  | —       | Filter by phone ID                                                                 |
| `limit`    | `integer` | `20`    | Number of sessions to return (1–100)                                               |

## Response

**Status: 200 OK**

```json theme={null}
{
  "sessions": [
    {
      "id": "sess_abc123",
      "phone_id": "abc123-def456",
      "instruction": "Open Instagram and like the first 3 posts",
      "status": "completed",
      "cost_usd": 0.42,
      "duration_ms": 45200,
      "num_turns": 12,
      "error": null,
      "created_at": "2024-01-15T10:30:00Z",
      "started_at": "2024-01-15T10:30:02Z",
      "completed_at": "2024-01-15T10:30:47Z"
    }
  ]
}
```

### Response Fields

| Field      | Type    | Description                                                                                               |
| ---------- | ------- | --------------------------------------------------------------------------------------------------------- |
| `sessions` | `array` | Array of session objects (see [Create Session](/api-reference/sessions/create-session) for field details) |

## Examples

### List Running Sessions

```bash theme={null}
curl "https://api.tapkit.ai/v1/sessions?status=running" \
  -H "X-API-Key: joot_..."
```

### Python

```python theme={null}
import requests

response = requests.get(
    "https://api.tapkit.ai/v1/sessions",
    headers={"X-API-Key": "joot_..."},
    params={"status": "running", "limit": 50}
)

sessions = response.json()["sessions"]
for s in sessions:
    print(f"{s['id']}: {s['status']} - {s['instruction'][:50]}")
```

## Related Endpoints

* [Create Session](/api-reference/sessions/create-session) - Start a new session
* [Get Session](/api-reference/sessions/get-session) - Get details for a specific session