> For the complete documentation index, see [llms.txt](https://cros-one.gitbook.io/cros.one/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cros-one.gitbook.io/cros.one/api-reference/start-session.md).

# Start Session

**Start a New Session**

**POST /session/start**

This endpoint creates a new session and returns a session ID. An existing session cannot provide a session ID during creation.

The session request can be parameterized with the following options:

* **session\_timeout**: The session timeout in minutes (resets with every operation performed in the session).
* **screenshot**: Whether to take a screenshot of the browser session.

**Request Example:**

```bash
bashCopyEditcurl --location \
--request POST 'https://api.cros.one/session/start' \
--header 'Authorization: Bearer your-api-key' \
--header 'Content-Type: application/json' \
--data '{
  "keep_alive": true,
  "session_timeout_minutes": 10,
  "screenshot": true
}'
```

**Response:**

```json
jsonCopyEdit{
  "session_id": "1234567890abcdef",
  "status": "active",
  "created_at": "2025-02-06T14:00:00.000Z",
  "last_accessed_at": "2025-02-06T14:05:00.000Z",
  "duration": "5 minutes",
  "timeout_minutes": 10,
  "error": null
}
```

**Fields in the Request Body:**

* **keep\_alive** (boolean, default: `false`): If true, the session will not be closed after the operation is completed.
* **screenshot** (boolean | null): Whether to include a screenshot in the response.
* **session\_timeout\_minutes** (integer, default: 5): Session timeout in minutes. The timeout cannot exceed the global timeout. Allowed range: `0 < x < 30`.
* **session\_id** (string | null): The ID of the session. A new session is created when not provided.

**Fields in the Response:**

* **session\_id** (string): The ID of the session (created or existing). Use this ID to interact with the session for the next operation.
* **status** (string): The status of the session. Available options: `active`, `closed`, `error`, `timed_out`.
* **created\_at** (string): The timestamp when the session was created.
* **last\_accessed\_at** (string): The timestamp of the last session access.
* **duration** (string): The session duration.
* **timeout\_minutes** (integer): Session timeout in minutes.
* **error** (string | null): An error message if the operation failed.