> ## Documentation Index > Fetch the complete documentation index at: https://docs.judt.ai/llms.txt > Use this file to discover all available pages before exploring further. # List session events > Returns the session's events in sequence order, after `cursor`. The cursor is an event's `sequence`: pass a page's `next_cursor`, or a session's `last_sequence` to get only what happens next. To follow the session live, send `Accept: text/event-stream`. The stream sends the following: - A `session.status` event, without an `id`, whose data is the `Session`. - Every event after the cursor, with `id` set to its sequence and `event` set to its type. - New events as they happen, and `message.delta` events with partial agent text. A `message.delta` event has no `id`, and its data is `{turn_id, text}`. The log doesn't store it. - A heartbeat comment every 15 seconds. The server closes the stream within 10 minutes. To resume, reconnect with `Last-Event-ID`. ## OpenAPI ````yaml /api-reference/openapi.json get /api/apps/{id}/sessions/{session_id}/events openapi: 3.1.0 info: title: Judt API version: 1.0.0 description: >- The Judt API creates and runs Apps. Each App has a sandbox, where you and agents edit and run its source, and a production deployment that serves it. ## Authentication Send an API token or an OAuth access token in the `Authorization` header. - **API token:** send it as a bearer token. A token belongs to one organization, and you create and revoke tokens in the dashboard. A token scoped to one App can reach only that App. An organization-wide token can also create a short-lived token for one App with `POST /api/tokens`, to give to an agent or an MCP client. - **OAuth access token:** an agent gets one when a person approves its access to one organization, so the person never handles a token. Reads need the `apps:read` scope, and changes need `apps:write`. To register and sign in, follow https://judt.ai/auth.md. Send the token as a bearer token, or with a DPoP proof if it's bound to a DPoP key. One access token can work on both this API and the MCP server at https://api.judt.ai/mcp. ## Sandboxes Creating an App reserves its address, but it doesn't start a sandbox or publish anything. There's no endpoint to start a sandbox. A request that needs the sandbox starts it first, so the first request after the sandbox goes idle takes longer. Files, Git, commands, commits, restores, previews, and deployments all need the sandbox. The sandbox stops on its own when it's idle. If `sandbox_status` is `failed`, the most recent start failed, and the API retries it while the sandbox is needed. ## Pagination A list returns one page at a time, in the form `{"results": [...], "has_more": true, "next_cursor": "CURSOR"}`. To get the next page, list again with `cursor` set to `next_cursor`, and the same `sort` and filters. Results that arrive while you page don't shift your pages. On the last page, `has_more` is `false`, and `next_cursor` still finds results added later. ## Retries A request that creates, changes, or deletes something returns `200` after the work is done, with the resource as it is afterward. To retry a request safely, send an `Idempotency-Key` header. For 30 days, a retry with the same key and input returns the first request's result instead of repeating the work. If you don't send a key, the API generates one and returns it in the `Idempotency-Key` response header. Setting and deleting a Secret take no key, because repeating them changes nothing. A visitor token or a preview link is created fresh each time, because nothing is stored to repeat. The API records file writes and deletes, commands, commits, and restores before it runs them. The response status tells you what to do next: - `503` or `504`: the action is recorded but not finished. To get its result, retry with the same key. A new key would run the action again. - `4xx` or `502`: the result is final. A retry with the same key returns the same response. A `504 request_timeout` response says how far the work got and which event to check. The work continues, and a retry with the same key picks it up. ## Troubleshooting To see what happened to an App's sandbox, deployments, and deletion, list its events with `GET /api/apps/{id}/events`. To see what the App's code did, including requests, output, exceptions, and failed builds, list its logs with `GET /api/apps/{id}/logs`. ## Time limits Requests have the following time limits: - Stopping the sandbox: 120 seconds. - File writes, commits, and restores: 120 seconds. - Commands: the command's `timeout_seconds`, up to 120 seconds, plus 60 seconds to stop it and save its result. - Publishing, unpublishing, deleting an App, and changing production settings: 540 seconds, including any sandbox start. If a file write, commit, restore, or command has to start the sandbox, it gets up to 120 more seconds. ## Errors An error returns a JSON body in the form `{"error": {"code": "CODE", "message": "MESSAGE", "detail": "DETAIL", "request_id": "REQUEST_ID"}}`. The `code` value is stable, so check it rather than `message`. The `detail` value is optional. When a parameter or a body field isn't valid, the request returns `400 invalid_request`, `message` names the field, and `detail` lists every problem if there's more than one. When the server rejects a credential, it returns a JSON error body and sets the `WWW-Authenticate` header. A `401` response includes the `resource_metadata` URL in `WWW-Authenticate` (RFC 9728): | Status | Error code / header | Cause | Action | |---|---|---|---| | `401` | `unauthenticated` | The request has no credential, or the API token or OAuth access token is invalid, expired, or revoked. | Send a valid API token or OAuth access token. | | `401` | `invalid_token` | `WWW-Authenticate` error when an API token or OAuth access token is expired, revoked, or issued for a different `resource` audience. | Refresh the access token, or request a token for the target server. | | `401` | `invalid_dpop_proof` | The `DPoP` proof header is missing, expired, replayed, or signed for a different HTTP method or URL. | Create a new DPoP proof for the request method and URL. | | `403` | `insufficient_scope` | The OAuth token does not have the required scope (`apps:read` or `apps:write`). | Request authorization with the scope named in `WWW-Authenticate`. | | `403` | `app_scoped_token` | An App-scoped API token called `POST /api/apps` or `POST /api/tokens`. | Use an organization-wide API token. | | `403` | `api_token_required` | An OAuth access token called `POST /api/tokens`. | Use an organization-wide API token. | | `403` | `sign_in_required` | A Personal Agent Session Token was used before the user signed in or after the user signed out. | Tell the user to sign in to the Session. | | `403` | `forbidden` | Your organization role (`member`) does not allow this action. | Ask an organization `owner` or `admin` to do the action. | servers: - url: https://api.judt.ai security: [] tags: - name: Account description: >- See who a credential acts for: the person, the organization, and what the credential can reach. - name: Apps description: Create, update, and delete Apps, and control who can reach them. - name: Tokens description: >- Create short-lived API tokens that reach one App, to give to an agent or an MCP client. - name: Secrets description: >- Store values, such as API keys, that an App reads at runtime. Responses never include Secret values. - name: Files description: Read and write the source files in an App's sandbox. - name: Sandbox description: >- Run commands, use Git, commit and restore source, and preview the App's sandbox. - name: Deployments description: Publish an App's source to production, and take it offline. - name: Monitoring description: See what happened to an App, and what its code did. - name: Templates description: The starting points for new Apps. - name: Agents description: >- Work with the in-product coding agent: sessions, turns, events, and the models it runs on. The agent itself works only through this API. - name: Feedback description: Tell the Judt team about bugs, friction, and anything else. paths: /api/apps/{id}/sessions/{session_id}/events: get: tags: - Agents summary: List session events description: >- Returns the session's events in sequence order, after `cursor`. The cursor is an event's `sequence`: pass a page's `next_cursor`, or a session's `last_sequence` to get only what happens next. To follow the session live, send `Accept: text/event-stream`. The stream sends the following: - A `session.status` event, without an `id`, whose data is the `Session`. - Every event after the cursor, with `id` set to its sequence and `event` set to its type. - New events as they happen, and `message.delta` events with partial agent text. A `message.delta` event has no `id`, and its data is `{turn_id, text}`. The log doesn't store it. - A heartbeat comment every 15 seconds. The server closes the stream within 10 minutes. To resume, reconnect with `Last-Event-ID`. operationId: list_session_events parameters: - name: id in: path required: true description: A unique ID that starts with `app_`. schema: type: string pattern: ^app_[0-9A-Za-z]{24}$ example: app_Zj7XhMgplmTJcp5Dk4vcYuk0 - name: session_id in: path required: true description: A unique ID that starts with `ses_`. schema: type: string pattern: ^ses_[0-9A-Za-z]{24}$ example: ses_Zj7XhMgplmTJcp5Dk4vcYuk0 - name: cursor in: query description: Returns only events whose sequence is greater than this value. schema: type: integer minimum: 0 default: 0 - name: limit in: query description: >- The maximum number of events to return. Applies only to JSON responses. schema: type: integer minimum: 1 maximum: 1000 default: 100 - name: Last-Event-ID in: header description: >- For streams, the sequence of the last event that you received. The stream resumes after it, and the header takes precedence over `cursor`. schema: type: integer minimum: 0 responses: '200': description: One page of events, or the live stream. content: application/json: schema: $ref: '#/components/schemas/AgentEventList' text/event-stream: schema: type: string description: Server-sent events, as the operation describes. '400': $ref: '#/components/responses/Error' '401': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' '404': $ref: '#/components/responses/Error' '410': $ref: '#/components/responses/Error' security: - ApiToken: [] components: schemas: AgentEventList: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: results: type: array items: oneOf: - type: object properties: sequence: type: integer exclusiveMinimum: 0 description: The event's position in the session's log. example: 12 turn_id: type: string description: The ID of the turn that the event belongs to. created_at: type: string format: date-time description: When the event happened. example: '2026-10-03T14:01:30.000Z' type: type: string const: message role: type: string enum: - user - agent description: Who wrote the message. text: type: string description: The message text. required: - sequence - turn_id - created_at - type - role - text additionalProperties: false title: message description: A message from the user or the agent. - type: object properties: sequence: type: integer exclusiveMinimum: 0 description: The event's position in the session's log. example: 12 turn_id: type: string description: The ID of the turn that the event belongs to. created_at: type: string format: date-time description: When the event happened. example: '2026-10-03T14:01:30.000Z' type: type: string const: turn.started model: type: string description: The model that the turn runs on. base_commit_id: description: The commit that the turn started from. type: - string - 'null' required: - sequence - turn_id - created_at - type - model - base_commit_id additionalProperties: false title: turn.started description: The turn started running. - type: object properties: sequence: type: integer exclusiveMinimum: 0 description: The event's position in the session's log. example: 12 turn_id: type: string description: The ID of the turn that the event belongs to. created_at: type: string format: date-time description: When the event happened. example: '2026-10-03T14:01:30.000Z' type: type: string const: tool.started call_id: type: string description: >- The ID that links a tool call's `tool.started` and `tool.completed` events. tool: type: string description: The tool's name. input: description: >- The tool's input. File contents are replaced by their path and size, and other inputs are truncated to 4 KiB. required: - sequence - turn_id - created_at - type - call_id - tool - input additionalProperties: false title: tool.started description: The agent called a tool. - type: object properties: sequence: type: integer exclusiveMinimum: 0 description: The event's position in the session's log. example: 12 turn_id: type: string description: The ID of the turn that the event belongs to. created_at: type: string format: date-time description: When the event happened. example: '2026-10-03T14:01:30.000Z' type: type: string const: tool.completed call_id: type: string description: >- The ID that links a tool call's `tool.started` and `tool.completed` events. tool: type: string description: The tool's name. status: type: string enum: - succeeded - failed description: Whether the tool call succeeded. output: description: The tool's output, truncated to 16 KiB. type: - string - 'null' error: anyOf: - type: object properties: code: type: string description: A stable code for the error. message: type: string description: A readable explanation of the error. required: - code - message additionalProperties: false - type: 'null' description: Why the tool call failed, or null if it succeeded. commit_id: description: The commit that the tool created, if any. type: string deployment_id: description: The deployment that the tool started, if any. type: string required: - sequence - turn_id - created_at - type - call_id - tool - status - output - error additionalProperties: false title: tool.completed description: A tool call finished. - type: object properties: sequence: type: integer exclusiveMinimum: 0 description: The event's position in the session's log. example: 12 turn_id: type: string description: The ID of the turn that the event belongs to. created_at: type: string format: date-time description: When the event happened. example: '2026-10-03T14:01:30.000Z' type: type: string const: input.requested input_request: type: object properties: id: type: string description: The input request's ID. kind: type: string const: secrets description: The kind of input that the agent needs. secrets: type: array items: type: object properties: name: type: string description: The Secret's name. provided: type: boolean description: True if the Secret is set; false otherwise. required: - name - provided additionalProperties: false description: >- The Secrets that the agent needs. To provide one, set it with `PUT /api/apps/{id}/secrets/{name}`. The turn resumes after all of them are set. The agent never receives their values. reason: type: string description: Why the agent needs the input, in the agent's words. expires_at: type: string format: date-time description: >- When the request expires. If no one provides or declines the input by then, the turn fails with `input_expired`. example: '2026-10-03T14:01:30.000Z' required: - id - kind - secrets - reason - expires_at additionalProperties: false description: A request for input from a person. required: - sequence - turn_id - created_at - type - input_request additionalProperties: false title: input.requested description: The agent needs input from a person, and the turn is waiting. - type: object properties: sequence: type: integer exclusiveMinimum: 0 description: The event's position in the session's log. example: 12 turn_id: type: string description: The ID of the turn that the event belongs to. created_at: type: string format: date-time description: When the event happened. example: '2026-10-03T14:01:30.000Z' type: type: string const: input.resolved input_request_id: type: string description: The ID of the input request. resolution: type: string enum: - provided - declined - expired description: How the request ended. message: description: The message sent with a decline, if any. type: string required: - sequence - turn_id - created_at - type - input_request_id - resolution additionalProperties: false title: input.resolved description: >- An input request was provided, declined, or expired, and the turn resumed or failed. - type: object properties: sequence: type: integer exclusiveMinimum: 0 description: The event's position in the session's log. example: 12 turn_id: type: string description: The ID of the turn that the event belongs to. created_at: type: string format: date-time description: When the event happened. example: '2026-10-03T14:01:30.000Z' type: type: string const: turn.completed usage: type: object properties: input_tokens: type: integer minimum: 0 description: The number of tokens the model read. example: 12840 output_tokens: type: integer minimum: 0 description: The number of tokens the model wrote. example: 1260 cache_read_tokens: type: integer minimum: 0 description: The number of input tokens read from the prompt cache. example: 9600 required: - input_tokens - output_tokens - cache_read_tokens additionalProperties: false description: The tokens that the turn used. required: - sequence - turn_id - created_at - type - usage additionalProperties: false title: turn.completed description: The turn finished successfully. - type: object properties: sequence: type: integer exclusiveMinimum: 0 description: The event's position in the session's log. example: 12 turn_id: type: string description: The ID of the turn that the event belongs to. created_at: type: string format: date-time description: When the event happened. example: '2026-10-03T14:01:30.000Z' type: type: string const: turn.failed usage: type: object properties: input_tokens: type: integer minimum: 0 description: The number of tokens the model read. example: 12840 output_tokens: type: integer minimum: 0 description: The number of tokens the model wrote. example: 1260 cache_read_tokens: type: integer minimum: 0 description: The number of input tokens read from the prompt cache. example: 9600 required: - input_tokens - output_tokens - cache_read_tokens additionalProperties: false description: The tokens that the turn used. error: type: object properties: code: type: string description: A stable code for the error. message: type: string description: A readable explanation of the error. required: - code - message additionalProperties: false description: Why the turn failed. required: - sequence - turn_id - created_at - type - usage - error additionalProperties: false title: turn.failed description: The turn failed. - type: object properties: sequence: type: integer exclusiveMinimum: 0 description: The event's position in the session's log. example: 12 turn_id: type: string description: The ID of the turn that the event belongs to. created_at: type: string format: date-time description: When the event happened. example: '2026-10-03T14:01:30.000Z' type: type: string const: turn.cancelled usage: type: object properties: input_tokens: type: integer minimum: 0 description: The number of tokens the model read. example: 12840 output_tokens: type: integer minimum: 0 description: The number of tokens the model wrote. example: 1260 cache_read_tokens: type: integer minimum: 0 description: The number of input tokens read from the prompt cache. example: 9600 required: - input_tokens - output_tokens - cache_read_tokens additionalProperties: false description: The tokens that the turn used. required: - sequence - turn_id - created_at - type - usage additionalProperties: false title: turn.cancelled description: The turn was canceled. description: The results in this page. has_more: type: boolean description: True if more results follow this page; false otherwise. next_cursor: description: >- Where the next page starts: to get it, list again with this value as `cursor`. A cursor from the last page later finds results added after it. Null if the list is empty. type: - string - 'null' required: - results - has_more - next_cursor additionalProperties: false Error: type: object required: - error properties: error: type: object required: - code - message - request_id properties: code: type: string description: A stable code for the error, such as `not_found`. message: type: string description: A readable explanation of the error. detail: type: string description: >- More information, if any: the sandbox's error, a provider message, or, for a `504`, how far the work got and the ID of its latest event. request_id: type: string description: The request's ID. Include it when you contact support. responses: Error: description: An error, with its code and the request ID. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: ApiToken: type: http scheme: bearer description: >- An API token for one organization. You create and revoke tokens in the dashboard. A token scoped to one App can reach only that App, so give that kind of token to an agent. An organization-wide token can create a short-lived one with `POST /api/tokens`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.