> ## Documentation Index > Fetch the complete documentation index at: https://docs.traversal.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a session > Starts a new investigation. The request returns immediately while Traversal investigates in the background — poll `GET /v1/sessions/{session_id}` until the session reaches the `idle` state to retrieve the result. Each organization is limited to **5 concurrent running sessions**. Exceeding the limit returns `429 Too Many Requests` with `retry_after`. ## OpenAPI ````yaml /api/openapi.yaml post /v1/sessions openapi: 3.1.0 info: title: Traversal Sessions API version: 1.0.0 description: > The V1 Sessions API lets you launch investigations, send follow-up questions, and retrieve results programmatically. Sessions are the same investigation primitive that powers the Traversal web application. All endpoints require a Bearer token. The authenticated user must have at least the `MEMBER` role within the organization, and the V1 API must be enabled for that organization — otherwise endpoints return `403 Forbidden`. servers: - url: https://api.traversal.com description: Traversal API security: - bearerAuth: [] tags: - name: Sessions description: Create, list, retrieve, and continue investigation sessions. paths: /v1/sessions: post: tags: - Sessions summary: Create a session description: > Starts a new investigation. The request returns immediately while Traversal investigates in the background — poll `GET /v1/sessions/{session_id}` until the session reaches the `idle` state to retrieve the result. Each organization is limited to **5 concurrent running sessions**. Exceeding the limit returns `429 Too Many Requests` with `retry_after`. operationId: createSession requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateSessionRequest' examples: default: value: input: >- Our checkout service started returning 500 errors at 2024-03-15T14:30:00Z. Error rate jumped from 0.1% to 15%. title: Elevated error rate in checkout service time: '2024-03-15T14:30:00Z' idempotency_key: pagerduty-incident-P12345 responses: '200': description: >- Idempotency key matched an existing session; the existing session is returned unchanged. content: application/json: schema: $ref: '#/components/schemas/Session' '201': description: Session created. content: application/json: schema: $ref: '#/components/schemas/Session' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' components: schemas: CreateSessionRequest: type: object required: - input - idempotency_key properties: input: type: string description: The incident description or question to investigate. title: type: - string - 'null' maxLength: 256 description: A short label for the session. Auto-generated if omitted. time: type: - string - 'null' format: date-time description: ISO-8601 timestamp of when the incident occurred. idempotency_key: type: string maxLength: 128 description: | Unique client-generated key for idempotent creation. Submitting the same key twice returns the original session (with `200 OK`) rather than creating a new one. Use a value tied to the upstream event you are reacting to (e.g., a PagerDuty incident ID) so retries don't duplicate sessions. Session: type: object required: - id - status - input - created_at properties: id: type: string format: uuid description: Unique session identifier. example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 status: $ref: '#/components/schemas/SessionStatus' title: type: - string - 'null' description: Human-readable session title. example: Elevated error rate in checkout service input: type: string description: The original incident description or question. example: >- Our checkout service started returning 500 errors at 2024-03-15T14:30:00Z. Error rate jumped from 0.1% to 15%. created_at: type: string format: date-time description: When the session was created (UTC). example: '2024-03-15T14:35:00Z' updated_at: type: - string - 'null' format: date-time description: When the session was last updated (UTC). example: '2024-03-15T14:38:12Z' messages: type: - array - 'null' description: >- Conversation history. Only populated on `GET /v1/sessions/{session_id}`. items: $ref: '#/components/schemas/Message' SessionStatus: type: string enum: - running - idle - follow_up_running - failed description: | - `running` — a new investigation is in progress. - `idle` — investigation is complete and ready for follow-ups. - `follow_up_running` — a follow-up message is being processed. - `failed` — the investigation or follow-up errored or timed out. Message: type: object required: - id - role - markdown_content - created_at properties: id: type: string description: Unique message identifier. example: msg-001-uuid role: type: string enum: - user - assistant description: The author of the message. markdown_content: type: string description: Message content in Markdown. example: |- ## Investigation Summary I investigated the elevated error rate... created_at: type: string format: date-time description: When the message was created (UTC). example: '2024-03-15T14:38:12Z' Error: type: object required: - error properties: error: type: object required: - message properties: message: type: string description: Human-readable explanation of the error. retry_after: type: - integer - 'null' description: | Suggested seconds to wait before retrying. Present on `429` and `409` responses. When set, the response also includes a standard `Retry-After` HTTP header with the same value. responses: BadRequest: description: >- Invalid or missing fields in the request body. The `message` indicates which field failed validation. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Missing, invalid, or revoked API key. content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: >- V1 API not enabled for the organization, or the authenticated user has insufficient role. content: application/json: schema: $ref: '#/components/schemas/Error' TooManyRequests: description: >- Organization has reached the limit of 5 concurrent running sessions. Includes `retry_after` (default 30s). content: application/json: schema: $ref: '#/components/schemas/Error' InternalServerError: description: An unexpected error occurred on the server. content: application/json: schema: $ref: '#/components/schemas/Error' ServiceUnavailable: description: Investigation infrastructure is not available. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer description: | Bearer token in the `Authorization` header — for example, `Authorization: Bearer trv_ak_your_api_key_here`. Each key is bound to a specific user and organization. ````