# List logs (/api-reference/logs/listLogs) `GET /api/v2/logs` List logs with filters, selectable detail, sorting, and cursor pagination. `includeJobRuns=true` includes chat and Sim-agent jobs only with `sortBy=startedAt`, because other orderings are unsupported. `files` contains only run-produced files; use the files API for input attachments. Expired runs are permanently deleted by retention cleanup. Sim Cloud Free defaults to 30 days from run start; paid plans and billing-disabled deployments have no default expiry. Organization policies and workspace overrides can set an effective window. Billing-disabled cleanup requires enabled data retention. Runs referenced by active pauses are protected from cleanup. Workspace folder trees exceeding 10,000 folders return `413`. OAuth scope: `api:read`. ## Authentication ```json { "requirements": [ { "apiKey": [] }, { "oauthBearer": [ "api:read" ] } ], "schemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Send a personal or workspace API key in `X-API-Key`. See [key types and access](https://docs.sim.ai/api-reference/authentication#key-types); operations that reject workspace keys say so in their description." }, "oauthBearer": { "type": "oauth2", "description": "Send a Sim OAuth access token in `Authorization: Bearer`. See [OAuth authentication and scopes](https://docs.sim.ai/api-reference/authentication#oauth-access-tokens).", "flows": { "authorizationCode": { "authorizationUrl": "https://www.sim.ai/api/auth/oauth2/authorize", "tokenUrl": "https://www.sim.ai/api/auth/oauth2/token", "refreshUrl": "https://www.sim.ai/api/auth/oauth2/token", "scopes": { "api:read": "Read your workspaces, workflows, files, tables, and logs", "api:write": "Read, create, change, run, and delete resources in your workspaces", "offline_access": "Stay signed in without asking again" } } } } } } ``` Required OAuth scope: `api:read`. ## Request examples ### cURL ```bash curl --request GET 'https://www.sim.ai/api/v2/logs?workspaceId=string' \ --header 'X-API-Key: YOUR_API_KEY' ``` ### JavaScript ```javascript const response = await fetch("https://www.sim.ai/api/v2/logs?workspaceId=string", { "method": "GET", "headers": { "X-API-Key": "YOUR_API_KEY" } }); if (!response.ok) throw new Error(`HTTP ${response.status}`); const result = await response.json(); ``` ### Python ```python import requests response = requests.request( "GET", "https://www.sim.ai/api/v2/logs?workspaceId=string", headers={ "X-API-Key": "YOUR_API_KEY" }, ) response.raise_for_status() result = response.json() ``` ### Go ```go package main import ( "io" "net/http" "os" ) func check(err error) { if err != nil { panic(err) } } func must[T any](value T, err error) T { check(err) return value } func main() { request := must(http.NewRequest("GET", "https://www.sim.ai/api/v2/logs?workspaceId=string", nil)) request.Header.Set("X-API-Key", "YOUR_API_KEY") response := must(http.DefaultClient.Do(request)) defer response.Body.Close() if response.StatusCode >= 400 { panic(response.Status) } must(io.Copy(os.Stdout, response.Body)) } ``` ### Java ```java import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; public class Example { public static void main(String[] args) throws Exception { var builder = HttpRequest.newBuilder(URI.create("https://www.sim.ai/api/v2/logs?workspaceId=string")); builder.header("X-API-Key", "YOUR_API_KEY"); var request = builder.method("GET", HttpRequest.BodyPublishers.noBody()).build(); var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofInputStream()); try (var body = response.body()) { if (response.statusCode() >= 400) throw new IllegalStateException("HTTP " + response.statusCode()); body.transferTo(System.out); } } } ``` ### C# ```csharp using System; using System.IO; using System.Net.Http; using System.Text; using var client = new HttpClient(); using var request = new HttpRequestMessage(new HttpMethod("GET"), "https://www.sim.ai/api/v2/logs?workspaceId=string"); request.Headers.TryAddWithoutValidation("X-API-Key", "YOUR_API_KEY"); using var response = await client.SendAsync(request, HttpCompletionOption.ResponseHeadersRead); response.EnsureSuccessStatusCode(); await response.Content.CopyToAsync(Console.OpenStandardOutput()); ``` ## Parameters ```json [ { "name": "workspaceId", "in": "query", "required": true, "description": "Workspace whose execution logs should be returned.", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Workspace whose execution logs should be returned." } }, { "name": "workflowIds", "in": "query", "required": false, "description": "Comma-separated workflow identifiers to include. An empty entry is rejected. At most 200 entries.", "schema": { "type": "string", "description": "Comma-separated workflow identifiers to include. An empty entry is rejected. At most 200 entries." } }, { "name": "triggers", "in": "query", "required": false, "description": "Comma-separated, lowercase trigger types or webhook provider IDs. Matching is exact and case-sensitive; unknown values select no runs. An empty entry is rejected. The sentinel `all` disables this filter, even when listed with other values. At most 100 entries.", "schema": { "type": "string", "description": "Comma-separated, lowercase trigger types or webhook provider IDs. Matching is exact and case-sensitive; unknown values select no runs. An empty entry is rejected. The sentinel `all` disables this filter, even when listed with other values. At most 100 entries." } }, { "name": "level", "in": "query", "required": false, "description": "Severity level to include.", "schema": { "type": "string", "enum": [ "info", "error" ], "description": "Severity level to include." } }, { "name": "startDate", "in": "query", "required": false, "description": "Only include runs started at or after this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant.", "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "Only include runs started at or after this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant." } }, { "name": "endDate", "in": "query", "required": false, "description": "Only include runs started at or before this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant.", "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "Only include runs started at or before this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant." } }, { "name": "minDurationMs", "in": "query", "required": false, "description": "Minimum total execution duration in milliseconds. Whole milliseconds from 0 to 2147483647; the stored duration is a 32-bit integer, so a fractional or out-of-range bound is rejected.", "schema": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Minimum total execution duration in milliseconds. Whole milliseconds from 0 to 2147483647; the stored duration is a 32-bit integer, so a fractional or out-of-range bound is rejected." } }, { "name": "maxDurationMs", "in": "query", "required": false, "description": "Maximum total execution duration in milliseconds. Whole milliseconds from 0 to 2147483647; the stored duration is a 32-bit integer, so a fractional or out-of-range bound is rejected.", "schema": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Maximum total execution duration in milliseconds. Whole milliseconds from 0 to 2147483647; the stored duration is a 32-bit integer, so a fractional or out-of-range bound is rejected." } }, { "name": "minCost", "in": "query", "required": false, "description": "Minimum execution cost in USD, from 0 to 1000000. A run is never charged a negative amount, so a negative bound is rejected rather than treated as a filter that matches every run.", "schema": { "type": "number", "minimum": 0, "maximum": 1000000, "description": "Minimum execution cost in USD, from 0 to 1000000. A run is never charged a negative amount, so a negative bound is rejected rather than treated as a filter that matches every run." } }, { "name": "maxCost", "in": "query", "required": false, "description": "Maximum execution cost in USD, from 0 to 1000000. A run is never charged a negative amount, so a negative bound is rejected rather than treated as a filter that matches every run.", "schema": { "type": "number", "minimum": 0, "maximum": 1000000, "description": "Maximum execution cost in USD, from 0 to 1000000. A run is never charged a negative amount, so a negative bound is rejected rather than treated as a filter that matches every run." } }, { "name": "model", "in": "query", "required": false, "description": "AI model used during execution.", "schema": { "type": "string", "description": "AI model used during execution." } }, { "name": "details", "in": "query", "required": false, "description": "Response detail level. `full` adds the `workflow` summary to every workflow run; a job run never carries one, whatever this is set to. `includeTraceSpans=true` and `includeFinalOutput=true` each imply `full`, so either one adds `workflow` even when `details=basic` is sent explicitly.", "schema": { "default": "basic", "type": "string", "enum": [ "basic", "full" ], "description": "Response detail level. `full` adds the `workflow` summary to every workflow run; a job run never carries one, whatever this is set to. `includeTraceSpans=true` and `includeFinalOutput=true` each imply `full`, so either one adds `workflow` even when `details=basic` is sent explicitly." } }, { "name": "includeTraceSpans", "in": "query", "required": false, "description": "Whether to include block-level trace spans. Implies `details=full`. Spans are pruned on their own retention schedule, so a run whose spans have aged out returns `traceSpans: []` rather than an error.", "schema": { "description": "Whether to include block-level trace spans. Implies `details=full`. Spans are pruned on their own retention schedule, so a run whose spans have aged out returns `traceSpans: []` rather than an error.", "type": "boolean" } }, { "name": "includeFinalOutput", "in": "query", "required": false, "description": "Whether to include the final workflow output. Implies `details=full`, so the `workflow` summary is present regardless of what `details` is set to.", "schema": { "description": "Whether to include the final workflow output. Implies `details=full`, so the `workflow` summary is present regardless of what `details` is set to.", "type": "boolean" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum log entries per page. When execution data is returned (`includeTraceSpans` or `includeFinalOutput`), a page holds at most 20 entries, and fewer when their stored traces are large; follow `nextCursor` for the rest. A page whose execution data is withheld by permissions is not capped. Values outside 1–1000 are truncated and clamped into that range rather than rejected. Defaults to 100.", "schema": { "description": "Maximum log entries per page. When execution data is returned (`includeTraceSpans` or `includeFinalOutput`), a page holds at most 20 entries, and fewer when their stored traces are large; follow `nextCursor` for the rest. A page whose execution data is withheld by permissions is not capped. Values outside 1–1000 are truncated and clamped into that range rather than rejected. Defaults to 100.", "type": "integer", "default": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.", "schema": { "description": "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.", "type": "string", "minLength": 1 } }, { "name": "includeHandledErrors", "in": "query", "required": false, "description": "Whether `level=error` also selects runs that finished at `info` after a block error was recovered by an error path. Off by default: such a run succeeded, so it is an error only to a caller auditing error handling. Every row reports `hasHandledErrors` whether or not this is set. Job runs carry no block trace, so the flag never widens that branch.", "schema": { "description": "Whether `level=error` also selects runs that finished at `info` after a block error was recovered by an error path. Off by default: such a run succeeded, so it is an error only to a caller auditing error handling. Every row reports `hasHandledErrors` whether or not this is set. Job runs carry no block trace, so the flag never widens that branch.", "type": "boolean" } }, { "name": "status", "in": "query", "required": false, "description": "Comma-separated execution statuses to include, from `pending` | `running` | `paused` | `redacting` | `completed` | `failed` | `cancelled`. An empty entry is rejected. ANDed with `level`, which reports severity rather than lifecycle.", "schema": { "type": "string", "description": "Comma-separated execution statuses to include, from `pending` | `running` | `paused` | `redacting` | `completed` | `failed` | `cancelled`. An empty entry is rejected. ANDed with `level`, which reports severity rather than lifecycle." } }, { "name": "workflowName", "in": "query", "required": false, "description": "Case-insensitive substring match against the run's workflow name. Runs whose workflow has been deleted match nothing, because the name is no longer joinable.", "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Case-insensitive substring match against the run's workflow name. Runs whose workflow has been deleted match nothing, because the name is no longer joinable." } }, { "name": "includeJobRuns", "in": "query", "required": false, "description": "Include Chat and Sim-agent jobs alongside workflow runs. Jobs use `kind: \"job\"` and have no workflow or cost ledger. Workflow, folder, model, or status filters exclude jobs. This option is valid only when sorting by `startedAt`.", "schema": { "description": "Include Chat and Sim-agent jobs alongside workflow runs. Jobs use `kind: \"job\"` and have no workflow or cost ledger. Workflow, folder, model, or status filters exclude jobs. This option is valid only when sorting by `startedAt`.", "type": "boolean" } }, { "name": "runId", "in": "query", "required": false, "description": "Exact run identifier to match.", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Exact run identifier to match." } }, { "name": "sortBy", "in": "query", "required": false, "description": "Field used to sort the result. `durationMs` and `cost` are null until a run settles; those runs sort before recorded values in ascending order and after them in descending order. Only `startedAt` can order Chat and Sim-agent job runs, so any other value is rejected when job runs are included.", "schema": { "default": "startedAt", "description": "Field used to sort the result. `durationMs` and `cost` are null until a run settles; those runs sort before recorded values in ascending order and after them in descending order. Only `startedAt` can order Chat and Sim-agent job runs, so any other value is rejected when job runs are included.", "type": "string", "enum": [ "startedAt", "durationMs", "cost", "status" ] } }, { "name": "sortOrder", "in": "query", "required": false, "description": "Sort direction.", "schema": { "default": "desc", "description": "Sort direction.", "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "folderPaths", "in": "query", "required": false, "description": "Comma-separated workflow folder paths, including descendants. Up to 100 paths. Unknown folder paths contribute no matches.", "schema": { "type": "string", "description": "Comma-separated workflow folder paths, including descendants. Up to 100 paths. Unknown folder paths contribute no matches." } } ] ``` ## Responses ### 200 ```json { "description": "A page of execution logs matching the filters.", "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current window.", "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "title": "Rate limit", "description": "Maximum requests allowed in the current window." } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "title": "Rate limit remaining", "description": "Requests remaining in the current window." } }, "X-RateLimit-Reset": { "description": "ISO 8601 timestamp when the current rate-limit window resets.", "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "title": "Rate limit reset", "description": "ISO 8601 timestamp when the current rate-limit window resets." } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "workflow", "job" ], "description": "Whether the run executed a workflow or a Chat / Sim-agent job. Job runs appear only when `includeJobRuns=true`." }, "runId": { "type": "string", "description": "Unique run identifier." }, "workflowId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Workflow identifier, or null when unavailable." }, "deploymentVersionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Deployment version identifier, or null when unavailable." }, "status": { "type": "string", "enum": [ "pending", "running", "paused", "redacting", "completed", "failed", "cancelled" ], "description": "Current execution status, reported as persisted. `redacting` is transient while run output is scrubbed. `paused` is reported only when a resume attempt did not complete; a run held at a human-in-the-loop pause point reads `pending` here, and `paused` on the workflow run resources. Use those when the pause state matters." }, "level": { "type": "string", "description": "Log severity level." }, "trigger": { "type": "string", "description": "Trigger that started the run." }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO 8601 execution start timestamp." }, "endedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ], "description": "ISO 8601 execution end timestamp, or null while the run is active." }, "totalDurationMs": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Total execution duration in milliseconds, or null while unavailable." }, "cost": { "anyOf": [ { "type": "object", "properties": { "total": { "type": "number", "description": "Total execution cost in USD." } }, "required": [ "total" ], "additionalProperties": false }, { "type": "null" } ], "description": "Cost charged for the run, or null when the run has neither a recorded total nor an itemized ledger." }, "files": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Identifier to address this file by on the download endpoint." }, "name": { "type": "string", "description": "File name, including its extension." }, "size": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "File size in bytes." }, "type": { "type": "string", "description": "MIME type recorded for the file." }, "downloadPath": { "type": "string", "description": "Path to fetch this file's bytes from, relative to the API host." } }, "required": [ "id", "name", "size", "type", "downloadPath" ], "additionalProperties": false, "title": "Execution log file", "description": "A file produced by the run this log records." } }, { "type": "null" } ], "description": "Files the run produced, or null when none are recorded. Only the run's own output files appear; input attachments a caller supplied are addressed through the files API instead." }, "hasHandledErrors": { "type": "boolean", "description": "Whether a block in the run errored and was recovered by an error path. Such a run keeps `level: info`, so this is the only place the handled error shows at run level; pass `includeHandledErrors=true` with `level=error` to list these runs. Always false for a job run." }, "workflow": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Workflow identifier, or null when unavailable." }, "name": { "type": "string", "description": "Workflow name." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Workflow description, or null when unset." }, "deleted": { "type": "boolean", "description": "Whether the workflow has been deleted." } }, "required": [ "id", "name", "description", "deleted" ], "additionalProperties": false, "description": "Workflow summary for a full-detail result." }, "finalOutput": { "description": "Final workflow output." }, "traceSpans": { "type": "array", "items": { "title": "Log trace span", "description": "One recursive operation span in a workflow execution trace.", "type": "object", "properties": { "id": { "type": "string", "description": "Trace-span identifier." }, "name": { "type": "string", "description": "Trace-span name." }, "type": { "type": "string", "description": "Trace-span category." }, "duration": { "type": "number", "description": "Current trace-span duration in milliseconds." }, "durationMs": { "type": "number", "description": "Compatibility field for span duration in milliseconds. Read `duration` for current trace spans." }, "startTime": { "type": "string", "description": "ISO 8601 span start timestamp." }, "endTime": { "type": "string", "description": "ISO 8601 span end timestamp." }, "status": { "type": "string", "description": "Trace-span status." }, "errorHandled": { "type": "boolean", "description": "Whether the recorded error was handled." }, "errorType": { "type": "string", "description": "Recorded error type." }, "errorMessage": { "type": "string", "description": "Recorded error message." }, "blockId": { "type": "string", "description": "Workflow block associated with the span." }, "input": { "description": "Input captured for the traced operation." }, "output": { "description": "Output captured for the traced operation." }, "tokens": { "anyOf": [ { "type": "number", "description": "Total tokens attributed to the span." }, { "type": "object", "properties": { "total": { "type": "number", "description": "Total tokens." }, "input": { "type": "number", "description": "Input tokens." }, "output": { "type": "number", "description": "Output tokens." } }, "additionalProperties": false } ], "description": "Token usage attributed to the span." }, "cost": { "type": "object", "properties": { "total": { "type": "number", "description": "Total span cost in USD." }, "input": { "type": "number", "description": "Input-token cost in USD." }, "output": { "type": "number", "description": "Output-token cost in USD." }, "toolCost": { "type": "number", "description": "Tool cost in USD." } }, "additionalProperties": false, "description": "Cost attributed to the span." }, "relativeStartMs": { "type": "number", "description": "Offset from the root span in milliseconds." }, "contentWithheld": { "type": "boolean", "const": true, "description": "Present when the log projection withheld some or all of this span's content (input, output, thinking, error message, tool-call or provider-segment content) because it could not be proven safe to display. Status, timing, and usage remain. A withheld content field is omitted whole, never a key inside it: a content field absent from a span carrying this marker may exist on the run but was not returned, while a key missing inside a content field that is present is genuinely absent." }, "toolCalls": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Tool-call identifier." }, "name": { "type": "string", "description": "Invoked tool name." }, "arguments": { "description": "Arguments supplied to the tool call." }, "result": { "description": "Value returned by the tool call." }, "error": { "type": "string", "description": "Tool-call error message." }, "startTime": { "type": "string", "description": "ISO 8601 tool-call start timestamp." }, "endTime": { "type": "string", "description": "ISO 8601 tool-call end timestamp." }, "duration": { "type": "number", "description": "Tool-call duration in milliseconds." } }, "additionalProperties": { "description": "Additional provider-specific tool-call metadata." } }, "description": "Tool calls recorded by the span." }, "children": { "type": "array", "items": { "$ref": "#/components/schemas/LogTraceSpan" }, "description": "Nested child trace spans." } }, "required": [ "id", "name", "type" ], "additionalProperties": { "description": "Additional provider-specific trace-span metadata." } }, "description": "Block-level execution trace spans." } }, "required": [ "kind", "runId", "workflowId", "deploymentVersionId", "status", "level", "trigger", "startedAt", "endedAt", "totalDurationMs", "cost", "files", "hasHandledErrors" ], "additionalProperties": false, "title": "Execution log summary", "description": "Summary information for one workflow execution log." }, "description": "Items in the current page." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself." } }, "required": [ "data", "nextCursor" ], "additionalProperties": false, "title": "Log list response", "description": "A cursor-paginated page of workflow execution logs.", "examples": [ { "data": [ { "kind": "workflow", "runId": "e4f8d2b6-9a1c-4e3d-8b7f-5c0a2d9e6f13", "workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36", "deploymentVersionId": "dep_2c4e6a8b0d1f", "status": "completed", "level": "info", "trigger": "api", "startedAt": "2026-01-15T10:30:00.000Z", "endedAt": "2026-01-15T10:30:01.250Z", "totalDurationMs": 1250, "cost": { "total": 0.0072 }, "hasHandledErrors": false, "files": [ { "id": "f1c3a7d0-4b52-4a8e-9f61-2d7c8b3e5a04", "name": "summary.pdf", "size": 18422, "type": "application/pdf", "downloadPath": "/api/v2/workflows/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36/runs/e4f8d2b6-9a1c-4e3d-8b7f-5c0a2d9e6f13/files/f1c3a7d0-4b52-4a8e-9f61-2d7c8b3e5a04" } ] } ], "nextCursor": "eyJzdGFydGVkQXQiOiIyMDI2LTAxLTE1VDEwOjMwOjAwMFoifQ==" } ] }, "examples": { "example1": { "summary": "Response example 1", "value": { "data": [ { "kind": "workflow", "runId": "e4f8d2b6-9a1c-4e3d-8b7f-5c0a2d9e6f13", "workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36", "deploymentVersionId": "dep_2c4e6a8b0d1f", "status": "completed", "level": "info", "trigger": "api", "startedAt": "2026-01-15T10:30:00.000Z", "endedAt": "2026-01-15T10:30:01.250Z", "totalDurationMs": 1250, "cost": { "total": 0.0072 }, "hasHandledErrors": false, "files": [ { "id": "f1c3a7d0-4b52-4a8e-9f61-2d7c8b3e5a04", "name": "summary.pdf", "size": 18422, "type": "application/pdf", "downloadPath": "/api/v2/workflows/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36/runs/e4f8d2b6-9a1c-4e3d-8b7f-5c0a2d9e6f13/files/f1c3a7d0-4b52-4a8e-9f61-2d7c8b3e5a04" } ] } ], "nextCursor": "eyJzdGFydGVkQXQiOiIyMDI2LTAxLTE1VDEwOjMwOjAwMFoifQ==" } } } } } } ``` ### 400 ```json { "description": "The request is invalid. This includes a query parameter sent with no value (`?limit=`, `?search=`), which is rejected rather than read as zero, empty, or the parameter default — omit the parameter instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.", "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INSUFFICIENT_WORKSPACE_ROLE", "PERSONAL_API_KEYS_DISABLED", "WORKSPACE_KEY_OPERATION_NOT_PERMITTED", "PRINCIPAL_KIND_NOT_PERMITTED", "ORGANIZATION_MEMBERSHIP_REQUIRED", "ORGANIZATION_ADMIN_REQUIRED", "ENTERPRISE_PLAN_REQUIRED", "SSO_DISABLED", "SSO_DOMAIN_NOT_VERIFIED", "SSO_PROVIDER_LIMIT_REACHED", "ORGANIZATION_PLAN_REQUIRED", "AUDIT_LOGS_DISABLED", "ACCESS_REQUESTS_DISABLED", "ACCESS_REQUEST_ORGANIZATION_REQUIRED", "SKILL_EDITOR_ACCESS_REQUIRED", "SECRET_ADMIN_ACCESS_REQUIRED", "WORKSPACE_RESOURCE_LIMIT_REACHED", "PUBLIC_SHARING_NOT_ALLOWED", "CREDENTIAL_ADMIN_ACCESS_REQUIRED", "MCP_SERVER_URL_NOT_ALLOWED", "WORKSPACE_PLAN_CAPABILITY_REQUIRED", "CHAT_AUTH_MODE_NOT_PERMITTED", "CONNECTOR_MANAGED_RESOURCE_READ_ONLY", "PERMISSION_GROUP_CAPABILITY_BLOCKED", "INTEGRATION_NOT_ALLOWED", "INSUFFICIENT_SCOPE", "SCIM_MANAGED_MEMBERSHIP" ], "title": "Forbidden detail code", "description": "Stable cause code for an actionable `403` response." } }, "required": [ "code" ], "additionalProperties": { "description": "Additional context for this refusal." }, "title": "Actionable forbidden details", "description": "Machine-readable cause and optional context for an actionable `403` response." }, { "description": "Other structured context defined by the specific error." } ] } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "Canonical error details." } }, "required": [ "error" ], "additionalProperties": false, "title": "v2 error response", "description": "Canonical error envelope returned by the public v2 API.", "examples": [ { "error": { "code": "BAD_REQUEST", "message": "The request is invalid." } } ] }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request" } } } } } ``` ### 401 ```json { "description": "The API credential is missing or invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.", "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INSUFFICIENT_WORKSPACE_ROLE", "PERSONAL_API_KEYS_DISABLED", "WORKSPACE_KEY_OPERATION_NOT_PERMITTED", "PRINCIPAL_KIND_NOT_PERMITTED", "ORGANIZATION_MEMBERSHIP_REQUIRED", "ORGANIZATION_ADMIN_REQUIRED", "ENTERPRISE_PLAN_REQUIRED", "SSO_DISABLED", "SSO_DOMAIN_NOT_VERIFIED", "SSO_PROVIDER_LIMIT_REACHED", "ORGANIZATION_PLAN_REQUIRED", "AUDIT_LOGS_DISABLED", "ACCESS_REQUESTS_DISABLED", "ACCESS_REQUEST_ORGANIZATION_REQUIRED", "SKILL_EDITOR_ACCESS_REQUIRED", "SECRET_ADMIN_ACCESS_REQUIRED", "WORKSPACE_RESOURCE_LIMIT_REACHED", "PUBLIC_SHARING_NOT_ALLOWED", "CREDENTIAL_ADMIN_ACCESS_REQUIRED", "MCP_SERVER_URL_NOT_ALLOWED", "WORKSPACE_PLAN_CAPABILITY_REQUIRED", "CHAT_AUTH_MODE_NOT_PERMITTED", "CONNECTOR_MANAGED_RESOURCE_READ_ONLY", "PERMISSION_GROUP_CAPABILITY_BLOCKED", "INTEGRATION_NOT_ALLOWED", "INSUFFICIENT_SCOPE", "SCIM_MANAGED_MEMBERSHIP" ], "title": "Forbidden detail code", "description": "Stable cause code for an actionable `403` response." } }, "required": [ "code" ], "additionalProperties": { "description": "Additional context for this refusal." }, "title": "Actionable forbidden details", "description": "Machine-readable cause and optional context for an actionable `403` response." }, { "description": "Other structured context defined by the specific error." } ] } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "Canonical error details." } }, "required": [ "error" ], "additionalProperties": false, "title": "v2 error response", "description": "Canonical error envelope returned by the public v2 API.", "examples": [ { "error": { "code": "BAD_REQUEST", "message": "The request is invalid." } } ] }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Authentication required" } } } } } ``` ### 403 ```json { "description": "The caller lacks the rights this operation requires. When the cause is one a caller can act on, `error.details.code` names it. A resource in a workspace the caller cannot reach at all answers `404` instead, so absence and denial are indistinguishable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.", "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INSUFFICIENT_WORKSPACE_ROLE", "PERSONAL_API_KEYS_DISABLED", "WORKSPACE_KEY_OPERATION_NOT_PERMITTED", "PRINCIPAL_KIND_NOT_PERMITTED", "ORGANIZATION_MEMBERSHIP_REQUIRED", "ORGANIZATION_ADMIN_REQUIRED", "ENTERPRISE_PLAN_REQUIRED", "SSO_DISABLED", "SSO_DOMAIN_NOT_VERIFIED", "SSO_PROVIDER_LIMIT_REACHED", "ORGANIZATION_PLAN_REQUIRED", "AUDIT_LOGS_DISABLED", "ACCESS_REQUESTS_DISABLED", "ACCESS_REQUEST_ORGANIZATION_REQUIRED", "SKILL_EDITOR_ACCESS_REQUIRED", "SECRET_ADMIN_ACCESS_REQUIRED", "WORKSPACE_RESOURCE_LIMIT_REACHED", "PUBLIC_SHARING_NOT_ALLOWED", "CREDENTIAL_ADMIN_ACCESS_REQUIRED", "MCP_SERVER_URL_NOT_ALLOWED", "WORKSPACE_PLAN_CAPABILITY_REQUIRED", "CHAT_AUTH_MODE_NOT_PERMITTED", "CONNECTOR_MANAGED_RESOURCE_READ_ONLY", "PERMISSION_GROUP_CAPABILITY_BLOCKED", "INTEGRATION_NOT_ALLOWED", "INSUFFICIENT_SCOPE", "SCIM_MANAGED_MEMBERSHIP" ], "title": "Forbidden detail code", "description": "Stable cause code for an actionable `403` response." } }, "required": [ "code" ], "additionalProperties": { "description": "Additional context for this refusal." }, "title": "Actionable forbidden details", "description": "Machine-readable cause and optional context for an actionable `403` response." }, { "description": "Other structured context defined by the specific error." } ] } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "Canonical error details." } }, "required": [ "error" ], "additionalProperties": false, "title": "v2 error response", "description": "Canonical error envelope returned by the public v2 API.", "examples": [ { "error": { "code": "BAD_REQUEST", "message": "The request is invalid." } } ] }, "example": { "error": { "code": "FORBIDDEN", "message": "Insufficient workspace permissions", "details": { "code": "INSUFFICIENT_WORKSPACE_ROLE" } } } } } } ``` ### 404 ```json { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.", "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INSUFFICIENT_WORKSPACE_ROLE", "PERSONAL_API_KEYS_DISABLED", "WORKSPACE_KEY_OPERATION_NOT_PERMITTED", "PRINCIPAL_KIND_NOT_PERMITTED", "ORGANIZATION_MEMBERSHIP_REQUIRED", "ORGANIZATION_ADMIN_REQUIRED", "ENTERPRISE_PLAN_REQUIRED", "SSO_DISABLED", "SSO_DOMAIN_NOT_VERIFIED", "SSO_PROVIDER_LIMIT_REACHED", "ORGANIZATION_PLAN_REQUIRED", "AUDIT_LOGS_DISABLED", "ACCESS_REQUESTS_DISABLED", "ACCESS_REQUEST_ORGANIZATION_REQUIRED", "SKILL_EDITOR_ACCESS_REQUIRED", "SECRET_ADMIN_ACCESS_REQUIRED", "WORKSPACE_RESOURCE_LIMIT_REACHED", "PUBLIC_SHARING_NOT_ALLOWED", "CREDENTIAL_ADMIN_ACCESS_REQUIRED", "MCP_SERVER_URL_NOT_ALLOWED", "WORKSPACE_PLAN_CAPABILITY_REQUIRED", "CHAT_AUTH_MODE_NOT_PERMITTED", "CONNECTOR_MANAGED_RESOURCE_READ_ONLY", "PERMISSION_GROUP_CAPABILITY_BLOCKED", "INTEGRATION_NOT_ALLOWED", "INSUFFICIENT_SCOPE", "SCIM_MANAGED_MEMBERSHIP" ], "title": "Forbidden detail code", "description": "Stable cause code for an actionable `403` response." } }, "required": [ "code" ], "additionalProperties": { "description": "Additional context for this refusal." }, "title": "Actionable forbidden details", "description": "Machine-readable cause and optional context for an actionable `403` response." }, { "description": "Other structured context defined by the specific error." } ] } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "Canonical error details." } }, "required": [ "error" ], "additionalProperties": false, "title": "v2 error response", "description": "Canonical error envelope returned by the public v2 API.", "examples": [ { "error": { "code": "BAD_REQUEST", "message": "The request is invalid." } } ] }, "example": { "error": { "code": "NOT_FOUND", "message": "Not found" } } } } } ``` ### 413 ```json { "description": "The request, or a resource collection it must materialize, exceeds the allowed size: an oversized request body, a generated artifact past the download ceiling, or a workspace folder tree too large to load in full.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.", "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INSUFFICIENT_WORKSPACE_ROLE", "PERSONAL_API_KEYS_DISABLED", "WORKSPACE_KEY_OPERATION_NOT_PERMITTED", "PRINCIPAL_KIND_NOT_PERMITTED", "ORGANIZATION_MEMBERSHIP_REQUIRED", "ORGANIZATION_ADMIN_REQUIRED", "ENTERPRISE_PLAN_REQUIRED", "SSO_DISABLED", "SSO_DOMAIN_NOT_VERIFIED", "SSO_PROVIDER_LIMIT_REACHED", "ORGANIZATION_PLAN_REQUIRED", "AUDIT_LOGS_DISABLED", "ACCESS_REQUESTS_DISABLED", "ACCESS_REQUEST_ORGANIZATION_REQUIRED", "SKILL_EDITOR_ACCESS_REQUIRED", "SECRET_ADMIN_ACCESS_REQUIRED", "WORKSPACE_RESOURCE_LIMIT_REACHED", "PUBLIC_SHARING_NOT_ALLOWED", "CREDENTIAL_ADMIN_ACCESS_REQUIRED", "MCP_SERVER_URL_NOT_ALLOWED", "WORKSPACE_PLAN_CAPABILITY_REQUIRED", "CHAT_AUTH_MODE_NOT_PERMITTED", "CONNECTOR_MANAGED_RESOURCE_READ_ONLY", "PERMISSION_GROUP_CAPABILITY_BLOCKED", "INTEGRATION_NOT_ALLOWED", "INSUFFICIENT_SCOPE", "SCIM_MANAGED_MEMBERSHIP" ], "title": "Forbidden detail code", "description": "Stable cause code for an actionable `403` response." } }, "required": [ "code" ], "additionalProperties": { "description": "Additional context for this refusal." }, "title": "Actionable forbidden details", "description": "Machine-readable cause and optional context for an actionable `403` response." }, { "description": "Other structured context defined by the specific error." } ] } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "Canonical error details." } }, "required": [ "error" ], "additionalProperties": false, "title": "v2 error response", "description": "Canonical error envelope returned by the public v2 API.", "examples": [ { "error": { "code": "BAD_REQUEST", "message": "The request is invalid." } } ] }, "example": { "error": { "code": "PAYLOAD_TOO_LARGE", "message": "Request body is too large" } } } } } ``` ### 429 ```json { "description": "The caller exceeded the request rate limit.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset.", "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "title": "Retry after", "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset." } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.", "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INSUFFICIENT_WORKSPACE_ROLE", "PERSONAL_API_KEYS_DISABLED", "WORKSPACE_KEY_OPERATION_NOT_PERMITTED", "PRINCIPAL_KIND_NOT_PERMITTED", "ORGANIZATION_MEMBERSHIP_REQUIRED", "ORGANIZATION_ADMIN_REQUIRED", "ENTERPRISE_PLAN_REQUIRED", "SSO_DISABLED", "SSO_DOMAIN_NOT_VERIFIED", "SSO_PROVIDER_LIMIT_REACHED", "ORGANIZATION_PLAN_REQUIRED", "AUDIT_LOGS_DISABLED", "ACCESS_REQUESTS_DISABLED", "ACCESS_REQUEST_ORGANIZATION_REQUIRED", "SKILL_EDITOR_ACCESS_REQUIRED", "SECRET_ADMIN_ACCESS_REQUIRED", "WORKSPACE_RESOURCE_LIMIT_REACHED", "PUBLIC_SHARING_NOT_ALLOWED", "CREDENTIAL_ADMIN_ACCESS_REQUIRED", "MCP_SERVER_URL_NOT_ALLOWED", "WORKSPACE_PLAN_CAPABILITY_REQUIRED", "CHAT_AUTH_MODE_NOT_PERMITTED", "CONNECTOR_MANAGED_RESOURCE_READ_ONLY", "PERMISSION_GROUP_CAPABILITY_BLOCKED", "INTEGRATION_NOT_ALLOWED", "INSUFFICIENT_SCOPE", "SCIM_MANAGED_MEMBERSHIP" ], "title": "Forbidden detail code", "description": "Stable cause code for an actionable `403` response." } }, "required": [ "code" ], "additionalProperties": { "description": "Additional context for this refusal." }, "title": "Actionable forbidden details", "description": "Machine-readable cause and optional context for an actionable `403` response." }, { "description": "Other structured context defined by the specific error." } ] } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "Canonical error details." } }, "required": [ "error" ], "additionalProperties": false, "title": "v2 error response", "description": "Canonical error envelope returned by the public v2 API.", "examples": [ { "error": { "code": "BAD_REQUEST", "message": "The request is invalid." } } ] }, "example": { "error": { "code": "RATE_LIMITED", "message": "API rate limit exceeded", "details": { "retryAfter": "2026-01-01T00:00:30.000Z" } } } } } } ``` ### 500 ```json { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.", "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INSUFFICIENT_WORKSPACE_ROLE", "PERSONAL_API_KEYS_DISABLED", "WORKSPACE_KEY_OPERATION_NOT_PERMITTED", "PRINCIPAL_KIND_NOT_PERMITTED", "ORGANIZATION_MEMBERSHIP_REQUIRED", "ORGANIZATION_ADMIN_REQUIRED", "ENTERPRISE_PLAN_REQUIRED", "SSO_DISABLED", "SSO_DOMAIN_NOT_VERIFIED", "SSO_PROVIDER_LIMIT_REACHED", "ORGANIZATION_PLAN_REQUIRED", "AUDIT_LOGS_DISABLED", "ACCESS_REQUESTS_DISABLED", "ACCESS_REQUEST_ORGANIZATION_REQUIRED", "SKILL_EDITOR_ACCESS_REQUIRED", "SECRET_ADMIN_ACCESS_REQUIRED", "WORKSPACE_RESOURCE_LIMIT_REACHED", "PUBLIC_SHARING_NOT_ALLOWED", "CREDENTIAL_ADMIN_ACCESS_REQUIRED", "MCP_SERVER_URL_NOT_ALLOWED", "WORKSPACE_PLAN_CAPABILITY_REQUIRED", "CHAT_AUTH_MODE_NOT_PERMITTED", "CONNECTOR_MANAGED_RESOURCE_READ_ONLY", "PERMISSION_GROUP_CAPABILITY_BLOCKED", "INTEGRATION_NOT_ALLOWED", "INSUFFICIENT_SCOPE", "SCIM_MANAGED_MEMBERSHIP" ], "title": "Forbidden detail code", "description": "Stable cause code for an actionable `403` response." } }, "required": [ "code" ], "additionalProperties": { "description": "Additional context for this refusal." }, "title": "Actionable forbidden details", "description": "Machine-readable cause and optional context for an actionable `403` response." }, { "description": "Other structured context defined by the specific error." } ] } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "Canonical error details." } }, "required": [ "error" ], "additionalProperties": false, "title": "v2 error response", "description": "Canonical error envelope returned by the public v2 API.", "examples": [ { "error": { "code": "BAD_REQUEST", "message": "The request is invalid." } } ] }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } ``` ### 503 ```json { "description": "A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before repeating a change after an uncertain response.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset.", "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "title": "Retry after", "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset." } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.", "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INSUFFICIENT_WORKSPACE_ROLE", "PERSONAL_API_KEYS_DISABLED", "WORKSPACE_KEY_OPERATION_NOT_PERMITTED", "PRINCIPAL_KIND_NOT_PERMITTED", "ORGANIZATION_MEMBERSHIP_REQUIRED", "ORGANIZATION_ADMIN_REQUIRED", "ENTERPRISE_PLAN_REQUIRED", "SSO_DISABLED", "SSO_DOMAIN_NOT_VERIFIED", "SSO_PROVIDER_LIMIT_REACHED", "ORGANIZATION_PLAN_REQUIRED", "AUDIT_LOGS_DISABLED", "ACCESS_REQUESTS_DISABLED", "ACCESS_REQUEST_ORGANIZATION_REQUIRED", "SKILL_EDITOR_ACCESS_REQUIRED", "SECRET_ADMIN_ACCESS_REQUIRED", "WORKSPACE_RESOURCE_LIMIT_REACHED", "PUBLIC_SHARING_NOT_ALLOWED", "CREDENTIAL_ADMIN_ACCESS_REQUIRED", "MCP_SERVER_URL_NOT_ALLOWED", "WORKSPACE_PLAN_CAPABILITY_REQUIRED", "CHAT_AUTH_MODE_NOT_PERMITTED", "CONNECTOR_MANAGED_RESOURCE_READ_ONLY", "PERMISSION_GROUP_CAPABILITY_BLOCKED", "INTEGRATION_NOT_ALLOWED", "INSUFFICIENT_SCOPE", "SCIM_MANAGED_MEMBERSHIP" ], "title": "Forbidden detail code", "description": "Stable cause code for an actionable `403` response." } }, "required": [ "code" ], "additionalProperties": { "description": "Additional context for this refusal." }, "title": "Actionable forbidden details", "description": "Machine-readable cause and optional context for an actionable `403` response." }, { "description": "Other structured context defined by the specific error." } ] } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "Canonical error details." } }, "required": [ "error" ], "additionalProperties": false, "title": "v2 error response", "description": "Canonical error envelope returned by the public v2 API.", "examples": [ { "error": { "code": "BAD_REQUEST", "message": "The request is invalid." } } ] }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable" } } } } } ``` ## Referenced schemas The following definitions preserve recursive references and composition exactly. ```json { "#/components/headers/X-RateLimit-Limit": { "description": "Maximum requests allowed in the current window.", "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "title": "Rate limit", "description": "Maximum requests allowed in the current window." } }, "#/components/headers/X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "title": "Rate limit remaining", "description": "Requests remaining in the current window." } }, "#/components/headers/X-RateLimit-Reset": { "description": "ISO 8601 timestamp when the current rate-limit window resets.", "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "title": "Rate limit reset", "description": "ISO 8601 timestamp when the current rate-limit window resets." } }, "#/components/schemas/V2LogListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V2LogListItem" }, "description": "Items in the current page." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself." } }, "required": [ "data", "nextCursor" ], "additionalProperties": false, "title": "Log list response", "description": "A cursor-paginated page of workflow execution logs.", "examples": [ { "data": [ { "kind": "workflow", "runId": "e4f8d2b6-9a1c-4e3d-8b7f-5c0a2d9e6f13", "workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36", "deploymentVersionId": "dep_2c4e6a8b0d1f", "status": "completed", "level": "info", "trigger": "api", "startedAt": "2026-01-15T10:30:00.000Z", "endedAt": "2026-01-15T10:30:01.250Z", "totalDurationMs": 1250, "cost": { "total": 0.0072 }, "hasHandledErrors": false, "files": [ { "id": "f1c3a7d0-4b52-4a8e-9f61-2d7c8b3e5a04", "name": "summary.pdf", "size": 18422, "type": "application/pdf", "downloadPath": "/api/v2/workflows/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36/runs/e4f8d2b6-9a1c-4e3d-8b7f-5c0a2d9e6f13/files/f1c3a7d0-4b52-4a8e-9f61-2d7c8b3e5a04" } ] } ], "nextCursor": "eyJzdGFydGVkQXQiOiIyMDI2LTAxLTE1VDEwOjMwOjAwMFoifQ==" } ] }, "#/components/schemas/V2LogListItem": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "workflow", "job" ], "description": "Whether the run executed a workflow or a Chat / Sim-agent job. Job runs appear only when `includeJobRuns=true`." }, "runId": { "type": "string", "description": "Unique run identifier." }, "workflowId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Workflow identifier, or null when unavailable." }, "deploymentVersionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Deployment version identifier, or null when unavailable." }, "status": { "type": "string", "enum": [ "pending", "running", "paused", "redacting", "completed", "failed", "cancelled" ], "description": "Current execution status, reported as persisted. `redacting` is transient while run output is scrubbed. `paused` is reported only when a resume attempt did not complete; a run held at a human-in-the-loop pause point reads `pending` here, and `paused` on the workflow run resources. Use those when the pause state matters." }, "level": { "type": "string", "description": "Log severity level." }, "trigger": { "type": "string", "description": "Trigger that started the run." }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO 8601 execution start timestamp." }, "endedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ], "description": "ISO 8601 execution end timestamp, or null while the run is active." }, "totalDurationMs": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Total execution duration in milliseconds, or null while unavailable." }, "cost": { "anyOf": [ { "type": "object", "properties": { "total": { "type": "number", "description": "Total execution cost in USD." } }, "required": [ "total" ], "additionalProperties": false }, { "type": "null" } ], "description": "Cost charged for the run, or null when the run has neither a recorded total nor an itemized ledger." }, "files": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/V2LogFile" } }, { "type": "null" } ], "description": "Files the run produced, or null when none are recorded. Only the run's own output files appear; input attachments a caller supplied are addressed through the files API instead." }, "hasHandledErrors": { "type": "boolean", "description": "Whether a block in the run errored and was recovered by an error path. Such a run keeps `level: info`, so this is the only place the handled error shows at run level; pass `includeHandledErrors=true` with `level=error` to list these runs. Always false for a job run." }, "workflow": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Workflow identifier, or null when unavailable." }, "name": { "type": "string", "description": "Workflow name." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Workflow description, or null when unset." }, "deleted": { "type": "boolean", "description": "Whether the workflow has been deleted." } }, "required": [ "id", "name", "description", "deleted" ], "additionalProperties": false, "description": "Workflow summary for a full-detail result." }, "finalOutput": { "description": "Final workflow output." }, "traceSpans": { "type": "array", "items": { "$ref": "#/components/schemas/LogTraceSpan" }, "description": "Block-level execution trace spans." } }, "required": [ "kind", "runId", "workflowId", "deploymentVersionId", "status", "level", "trigger", "startedAt", "endedAt", "totalDurationMs", "cost", "files", "hasHandledErrors" ], "additionalProperties": false, "title": "Execution log summary", "description": "Summary information for one workflow execution log." }, "#/components/schemas/V2LogFile": { "type": "object", "properties": { "id": { "type": "string", "description": "Identifier to address this file by on the download endpoint." }, "name": { "type": "string", "description": "File name, including its extension." }, "size": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "File size in bytes." }, "type": { "type": "string", "description": "MIME type recorded for the file." }, "downloadPath": { "type": "string", "description": "Path to fetch this file's bytes from, relative to the API host." } }, "required": [ "id", "name", "size", "type", "downloadPath" ], "additionalProperties": false, "title": "Execution log file", "description": "A file produced by the run this log records." }, "#/components/schemas/LogTraceSpan": { "title": "Log trace span", "description": "One recursive operation span in a workflow execution trace.", "type": "object", "properties": { "id": { "type": "string", "description": "Trace-span identifier." }, "name": { "type": "string", "description": "Trace-span name." }, "type": { "type": "string", "description": "Trace-span category." }, "duration": { "type": "number", "description": "Current trace-span duration in milliseconds." }, "durationMs": { "type": "number", "description": "Compatibility field for span duration in milliseconds. Read `duration` for current trace spans." }, "startTime": { "type": "string", "description": "ISO 8601 span start timestamp." }, "endTime": { "type": "string", "description": "ISO 8601 span end timestamp." }, "status": { "type": "string", "description": "Trace-span status." }, "errorHandled": { "type": "boolean", "description": "Whether the recorded error was handled." }, "errorType": { "type": "string", "description": "Recorded error type." }, "errorMessage": { "type": "string", "description": "Recorded error message." }, "blockId": { "type": "string", "description": "Workflow block associated with the span." }, "input": { "description": "Input captured for the traced operation." }, "output": { "description": "Output captured for the traced operation." }, "tokens": { "anyOf": [ { "type": "number", "description": "Total tokens attributed to the span." }, { "type": "object", "properties": { "total": { "type": "number", "description": "Total tokens." }, "input": { "type": "number", "description": "Input tokens." }, "output": { "type": "number", "description": "Output tokens." } }, "additionalProperties": false } ], "description": "Token usage attributed to the span." }, "cost": { "type": "object", "properties": { "total": { "type": "number", "description": "Total span cost in USD." }, "input": { "type": "number", "description": "Input-token cost in USD." }, "output": { "type": "number", "description": "Output-token cost in USD." }, "toolCost": { "type": "number", "description": "Tool cost in USD." } }, "additionalProperties": false, "description": "Cost attributed to the span." }, "relativeStartMs": { "type": "number", "description": "Offset from the root span in milliseconds." }, "contentWithheld": { "type": "boolean", "const": true, "description": "Present when the log projection withheld some or all of this span's content (input, output, thinking, error message, tool-call or provider-segment content) because it could not be proven safe to display. Status, timing, and usage remain. A withheld content field is omitted whole, never a key inside it: a content field absent from a span carrying this marker may exist on the run but was not returned, while a key missing inside a content field that is present is genuinely absent." }, "toolCalls": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Tool-call identifier." }, "name": { "type": "string", "description": "Invoked tool name." }, "arguments": { "description": "Arguments supplied to the tool call." }, "result": { "description": "Value returned by the tool call." }, "error": { "type": "string", "description": "Tool-call error message." }, "startTime": { "type": "string", "description": "ISO 8601 tool-call start timestamp." }, "endTime": { "type": "string", "description": "ISO 8601 tool-call end timestamp." }, "duration": { "type": "number", "description": "Tool-call duration in milliseconds." } }, "additionalProperties": { "description": "Additional provider-specific tool-call metadata." } }, "description": "Tool calls recorded by the span." }, "children": { "type": "array", "items": { "$ref": "#/components/schemas/LogTraceSpan" }, "description": "Nested child trace spans." } }, "required": [ "id", "name", "type" ], "additionalProperties": { "description": "Additional provider-specific trace-span metadata." } }, "#/components/responses/BadRequest": { "description": "The request is invalid. This includes a query parameter sent with no value (`?limit=`, `?search=`), which is rejected rather than read as zero, empty, or the parameter default — omit the parameter instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request" } } } } }, "#/components/schemas/V2Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.", "anyOf": [ { "$ref": "#/components/schemas/V2ActionableForbiddenDetails" }, { "description": "Other structured context defined by the specific error." } ] } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "Canonical error details." } }, "required": [ "error" ], "additionalProperties": false, "title": "v2 error response", "description": "Canonical error envelope returned by the public v2 API.", "examples": [ { "error": { "code": "BAD_REQUEST", "message": "The request is invalid." } } ] }, "#/components/schemas/V2ActionableForbiddenDetails": { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/V2ForbiddenDetailCode" } }, "required": [ "code" ], "additionalProperties": { "description": "Additional context for this refusal." }, "title": "Actionable forbidden details", "description": "Machine-readable cause and optional context for an actionable `403` response." }, "#/components/schemas/V2ForbiddenDetailCode": { "type": "string", "enum": [ "INSUFFICIENT_WORKSPACE_ROLE", "PERSONAL_API_KEYS_DISABLED", "WORKSPACE_KEY_OPERATION_NOT_PERMITTED", "PRINCIPAL_KIND_NOT_PERMITTED", "ORGANIZATION_MEMBERSHIP_REQUIRED", "ORGANIZATION_ADMIN_REQUIRED", "ENTERPRISE_PLAN_REQUIRED", "SSO_DISABLED", "SSO_DOMAIN_NOT_VERIFIED", "SSO_PROVIDER_LIMIT_REACHED", "ORGANIZATION_PLAN_REQUIRED", "AUDIT_LOGS_DISABLED", "ACCESS_REQUESTS_DISABLED", "ACCESS_REQUEST_ORGANIZATION_REQUIRED", "SKILL_EDITOR_ACCESS_REQUIRED", "SECRET_ADMIN_ACCESS_REQUIRED", "WORKSPACE_RESOURCE_LIMIT_REACHED", "PUBLIC_SHARING_NOT_ALLOWED", "CREDENTIAL_ADMIN_ACCESS_REQUIRED", "MCP_SERVER_URL_NOT_ALLOWED", "WORKSPACE_PLAN_CAPABILITY_REQUIRED", "CHAT_AUTH_MODE_NOT_PERMITTED", "CONNECTOR_MANAGED_RESOURCE_READ_ONLY", "PERMISSION_GROUP_CAPABILITY_BLOCKED", "INTEGRATION_NOT_ALLOWED", "INSUFFICIENT_SCOPE", "SCIM_MANAGED_MEMBERSHIP" ], "title": "Forbidden detail code", "description": "Stable cause code for an actionable `403` response." }, "#/components/responses/Unauthorized": { "description": "The API credential is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Authentication required" } } } } }, "#/components/responses/Forbidden": { "description": "The caller lacks the rights this operation requires. When the cause is one a caller can act on, `error.details.code` names it. A resource in a workspace the caller cannot reach at all answers `404` instead, so absence and denial are indistinguishable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Insufficient workspace permissions", "details": { "code": "INSUFFICIENT_WORKSPACE_ROLE" } } } } } }, "#/components/responses/NotFound": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "Not found" } } } } }, "#/components/responses/PayloadTooLarge": { "description": "The request, or a resource collection it must materialize, exceeds the allowed size: an oversized request body, a generated artifact past the download ceiling, or a workspace folder tree too large to load in full.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" }, "example": { "error": { "code": "PAYLOAD_TOO_LARGE", "message": "Request body is too large" } } } } }, "#/components/responses/RateLimited": { "description": "The caller exceeded the request rate limit.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "API rate limit exceeded", "details": { "retryAfter": "2026-01-01T00:00:30.000Z" } } } } } }, "#/components/headers/Retry-After": { "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset.", "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "title": "Retry after", "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset." } }, "#/components/responses/InternalError": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } }, "#/components/responses/ServiceUnavailable": { "description": "A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before repeating a change after an uncertain response.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable" } } } } } } ``` [Download OpenAPI specification](/openapi.json) Source: `openapi-v2-logs.json`, operation `listLogs`.