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

# Create Session

> Start a new autonomous agent session

Start a new agent session on a phone. The session creates a sandboxed environment where an AI agent autonomously executes your instruction.

## Request

```bash theme={null}
curl -X POST https://api.tapkit.ai/v1/sessions \
  -H "X-API-Key: joot_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"phone_id": "abc123", "instruction": "Open Instagram and like the first 3 posts"}'
```

### Request Body

```json theme={null}
{
  "phone_id": "abc123-def456",
  "instruction": "Open Instagram and like the first 3 posts"
}
```

| Field         | Type     | Required | Description                     |
| ------------- | -------- | -------- | ------------------------------- |
| `phone_id`    | `string` | Yes      | The phone to run the session on |
| `instruction` | `string` | Yes      | What the agent should do        |

## Response

**Status: 201 Created**

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

### Response Fields

| Field          | Type              | Description                                                         |
| -------------- | ----------------- | ------------------------------------------------------------------- |
| `id`           | `string`          | Session identifier                                                  |
| `phone_id`     | `string`          | Phone the session is running on                                     |
| `instruction`  | `string`          | The original instruction                                            |
| `status`       | `string`          | `creating`, `running`, `paused`, `completed`, `failed`, or `killed` |
| `cost_usd`     | `number \| null`  | Cost in USD (populated after completion)                            |
| `duration_ms`  | `integer \| null` | Duration in milliseconds (populated after completion)               |
| `num_turns`    | `integer \| null` | Number of agent turns (populated after completion)                  |
| `error`        | `string \| null`  | Error message if the session failed                                 |
| `created_at`   | `string`          | ISO 8601 creation timestamp                                         |
| `started_at`   | `string \| null`  | ISO 8601 timestamp when the session started running                 |
| `completed_at` | `string \| null`  | ISO 8601 timestamp when the session finished                        |

## Examples

### Python

```python theme={null}
import requests

response = requests.post(
    "https://api.tapkit.ai/v1/sessions",
    headers={
        "X-API-Key": "joot_...",
        "Content-Type": "application/json"
    },
    json={
        "phone_id": "abc123",
        "instruction": "Open Instagram and like the first 3 posts"
    }
)

session = response.json()
print(f"Session {session['id']} status: {session['status']}")
```

### Poll Until Complete

```python theme={null}
import time

session_id = session["id"]

while True:
    resp = requests.get(
        f"https://api.tapkit.ai/v1/sessions/{session_id}",
        headers={"X-API-Key": "joot_..."}
    )
    session = resp.json()

    if session["status"] in ("completed", "failed", "killed"):
        break

    time.sleep(2)

print(f"Done: {session['status']} in {session['duration_ms']}ms, {session['num_turns']} turns")
```

## Related Endpoints

* [List Sessions](/api-reference/sessions/list-sessions) - List all sessions
* [Get Session](/api-reference/sessions/get-session) - Get session details
* [Get Events](/api-reference/sessions/get-events) - Poll for session events
* [Stop Session](/api-reference/sessions/stop) - Kill a running session