{

"openapi": "3.1.0",

"info": {

"title": "Sim API v2 — Logs",

"description": "Version 2 of the Sim REST API for listing workflow execution logs and retrieving complete diagnostic run snapshots.",

"version": "2.0.0",

"contact": {

"name": "Sim Support",

"email": "help@sim.ai",

"url": "https://www.sim.ai"

},

"license": {

"name": "Apache 2.0",

"url": "https://www.apache.org/licenses/LICENSE-2.0.html"

}

},

"servers": [

{

"url": "https://www.sim.ai",

"description": "Production"

}

],

"tags": [

{

"name": "Logs",

"description": "Query workflow execution logs and retrieve complete run diagnostics."

}

],

"security": [

{

"apiKey": []

}

],

"paths": {

"/api/v2/logs": {

"get": {

"operationId": "listLogs",

"summary": "List Logs",

"description": "List workflow execution logs for a workspace with filters, selectable detail, and opaque cursor pagination. This list predates the shared sort convention: it has no `sortBy` (the sort column is fixed to execution start time) and spells the direction `order` rather than `sortOrder`. Trace spans are stored separately from the log row and are pruned on their own retention schedule: `includeTraceSpans=true` on a run whose stored spans have aged out returns `traceSpans: []` rather than an error, so an empty array does not mean the run recorded no spans.",

"tags": ["Logs"],

"parameters": [

{

"name": "workspaceId",

"in": "query",

"required": true,

"description": "Workspace whose execution logs should be returned.",

"schema": {

"type": "string",

"minLength": 1,

"description": "Workspace whose execution logs should be returned."

}

},

{

"name": "workflowIds",

"in": "query",

"required": false,

"description": "Comma-separated workflow identifiers to include.",

"schema": {

"type": "string",

"description": "Comma-separated workflow identifiers to include."

}

},

{

"name": "triggers",

"in": "query",

"required": false,

"description": "Comma-separated trigger types to include.",

"schema": {

"type": "string",

"description": "Comma-separated trigger types to include."

}

},

{

"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 ISO 8601 timestamp.",

"schema": {

"type": "string",

"description": "Only include runs started at or after this ISO 8601 timestamp."

}

},

{

"name": "endDate",

"in": "query",

"required": false,

"description": "Only include runs started at or before this ISO 8601 timestamp.",

"schema": {

"type": "string",

"description": "Only include runs started at or before this ISO 8601 timestamp."

}

},

{

"name": "minDurationMs",

"in": "query",

"required": false,

"description": "Minimum total execution duration in milliseconds.",

"schema": {

"type": "number",

"description": "Minimum total execution duration in milliseconds."

}

},

{

"name": "maxDurationMs",

"in": "query",

"required": false,

"description": "Maximum total execution duration in milliseconds.",

"schema": {

"type": "number",

"description": "Maximum total execution duration in milliseconds."

}

},

{

"name": "minCost",

"in": "query",

"required": false,

"description": "Minimum execution cost in USD.",

"schema": {

"type": "number",

"description": "Minimum execution cost in USD."

}

},

{

"name": "maxCost",

"in": "query",

"required": false,

"description": "Maximum execution cost in USD.",

"schema": {

"type": "number",

"description": "Maximum execution cost in USD."

}

},

{

"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.",

"schema": {

"default": "basic",

"type": "string",

"enum": ["basic", "full"],

"description": "Response detail level."

}

},

{

"name": "includeTraceSpans",

"in": "query",

"required": false,

"description": "Whether to include block-level trace spans.",

"schema": {

"description": "Whether to include block-level trace spans.",

"type": "boolean"

}

},

{

"name": "includeFinalOutput",

"in": "query",

"required": false,

"description": "Whether to include the final workflow output.",

"schema": {

"description": "Whether to include the final workflow output.",

"type": "boolean"

}

},

{

"name": "limit",

"in": "query",

"required": false,

"description": "Maximum log entries per page, clamped to 1–1000.",

"schema": {

"description": "Maximum log entries per page, clamped to 1–1000.",

"default": 100,

"type": "number"

}

},

{

"name": "cursor",

"in": "query",

"required": false,

"description": "Opaque cursor returned by a previous page.",

"schema": {

"type": "string",

"description": "Opaque cursor returned by a previous page."

}

},

{

"name": "order",

"in": "query",

"required": false,

"description": "Sort order by execution start time.",

"schema": {

"default": "desc",

"type": "string",

"enum": ["desc", "asc"],

"description": "Sort order by execution start time."

}

},

{

"name": "runId",

"in": "query",

"required": false,

"description": "Exact run identifier to match.",

"schema": {

"type": "string",

"minLength": 1,

"description": "Exact run identifier to match."

}

},

{

"name": "folderPaths",

"in": "query",

"required": false,

"description": "Comma-separated workflow folder paths to include.",

"schema": {

"type": "string",

"description": "Comma-separated workflow folder paths to include."

}

}

],

"responses": {

"200": {

"description": "A page of execution logs matching the filters.",

"headers": {

"X-RateLimit-Limit": {

"$ref": "#/components/headers/X-RateLimit-Limit"

},

"X-RateLimit-Remaining": {

"$ref": "#/components/headers/X-RateLimit-Remaining"

},

"X-RateLimit-Reset": {

"$ref": "#/components/headers/X-RateLimit-Reset"

}

},

"content": {

"application/json": {

"schema": {

"$ref": "#/components/schemas/V2LogListResponse"

}

}

}

},

"400": {

"$ref": "#/components/responses/BadRequest"

},

"401": {

"$ref": "#/components/responses/Unauthorized"

},

"403": {

"$ref": "#/components/responses/Forbidden"

},

"404": {

"$ref": "#/components/responses/NotFound"

},

"429": {

"$ref": "#/components/responses/RateLimited"

},

"500": {

"$ref": "#/components/responses/InternalError"

},

"503": {

"$ref": "#/components/responses/ServiceUnavailable"

}

}

}

},

"/api/v2/logs/{runId}": {

"get": {

"operationId": "getLog",

"summary": "Get Log",

"description": "Retrieve the diagnostic representation of a run, including its workflow snapshot, trace spans, final output, and cost. The returned `workflowState` snapshot has credential values redacted: OAuth credential references and secret (`password`) sub-block values are null, while `{{VAR}}` environment-variable references are preserved so consecutive snapshots stay diffable. Trace spans are stored separately from the log row and are pruned on their own retention schedule: a run whose stored spans have aged out returns `traceSpans: []` rather than an error, so an empty array does not mean the run recorded no spans.",

"tags": ["Logs"],

"parameters": [

{

"name": "runId",

"in": "path",

"required": true,

"description": "The unique run identifier shared by lifecycle and diagnostic resources.",

"schema": {

"type": "string",

"minLength": 1,

"description": "The unique run identifier shared by lifecycle and diagnostic resources."

}

}

],

"responses": {

"200": {

"description": "The requested diagnostic log representation.",

"headers": {

"X-RateLimit-Limit": {

"$ref": "#/components/headers/X-RateLimit-Limit"

},

"X-RateLimit-Remaining": {

"$ref": "#/components/headers/X-RateLimit-Remaining"

},

"X-RateLimit-Reset": {

"$ref": "#/components/headers/X-RateLimit-Reset"

}

},

"content": {

"application/json": {

"schema": {

"$ref": "#/components/schemas/V2LogDetailResponse"

}

}

}

},

"400": {

"$ref": "#/components/responses/BadRequest"

},

"401": {

"$ref": "#/components/responses/Unauthorized"

},

"403": {

"$ref": "#/components/responses/Forbidden"

},

"404": {

"$ref": "#/components/responses/NotFound"

},

"429": {

"$ref": "#/components/responses/RateLimited"

},

"500": {

"$ref": "#/components/responses/InternalError"

},

"503": {

"$ref": "#/components/responses/ServiceUnavailable"

}

}

}

}

},

"components": {

"securitySchemes": {

"apiKey": {

"type": "apiKey",

"in": "header",

"name": "X-API-Key",

"description": "Your Sim API key, personal or workspace-scoped. Generate one from the Sim dashboard under Settings > API Keys. A workspace API key is not accepted everywhere: operations that act on behalf of a specific human — administrative reads, secret access, and irreversible or governance-affecting writes — always reject it, whatever role the key carries. Each such operation says so in its own description, and the rejection surfaces as `403` unless the operation conceals unauthorized resources, in which case it is reported as `404`. Use a personal API key for those."

}

},

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

}

},

"Retry-After": {

"description": "Seconds to wait before retrying a rate-limited request.",

"schema": {

"type": "integer",

"minimum": 0,

"maximum": 9007199254740991,

"title": "Retry after",

"description": "Seconds to wait before retrying a rate-limited request."

}

},

"X-Run-Id": {

"description": "Identifier assigned to the workflow run.",

"schema": {

"type": "string",

"minLength": 1,

"title": "Run identifier",

"description": "Identifier assigned to the workflow run."

}

}

},

"responses": {

"BadRequest": {

"description": "The request is invalid.",

"content": {

"application/json": {

"schema": {

"$ref": "#/components/schemas/V2Error"

}

}

}

},

"Unauthorized": {

"description": "The API key is missing or invalid.",

"content": {

"application/json": {

"schema": {

"$ref": "#/components/schemas/V2Error"

}

}

}

},

"UsageLimitExceeded": {

"description": "The workspace has exceeded its usage or billing limits.",

"content": {

"application/json": {

"schema": {

"$ref": "#/components/schemas/V2Error"

}

}

}

},

"Forbidden": {

"description": "The caller lacks access to the resource.",

"content": {

"application/json": {

"schema": {

"$ref": "#/components/schemas/V2Error"

}

}

}

},

"NotFound": {

"description": "The requested resource was not found.",

"content": {

"application/json": {

"schema": {

"$ref": "#/components/schemas/V2Error"

}

}

}

},

"Conflict": {

"description": "The request conflicts with current resource state.",

"content": {

"application/json": {

"schema": {

"$ref": "#/components/schemas/V2Error"

}

}

}

},

"RunIdConflict": {

"description": "The run cannot be started. Two causes share this status, distinguished by `error.details.code`: `RUN_ID_CONFLICT` when the supplied `X-Run-Id` is already associated with a different request, and `CALL_CHAIN_DEPTH_EXCEEDED` when the incoming `X-Sim-Via` chain has already reached the maximum workflow-to-workflow call depth.",

"headers": {

"X-Run-Id": {

"$ref": "#/components/headers/X-Run-Id"

}

},

"content": {

"application/json": {

"schema": {

"$ref": "#/components/schemas/V2Error"

}

}

}

},

"Gone": {

"description": "The requested generated resource has expired.",

"content": {

"application/json": {

"schema": {

"$ref": "#/components/schemas/V2Error"

}

}

}

},

"PayloadTooLarge": {

"description": "The request, or a resource collection it must materialize, exceeds the allowed size. Besides an oversized request body, this covers a generated artifact that renders past the download ceiling and a workspace folder tree too large to load in full.",

"content": {

"application/json": {

"schema": {

"$ref": "#/components/schemas/V2Error"

}

}

}

},

"UnsupportedMediaType": {

"description": "The request uses an unsupported media type.",

"content": {

"application/json": {

"schema": {

"$ref": "#/components/schemas/V2Error"

}

}

}

},

"Locked": {

"description": "The resource is locked and cannot be modified.",

"content": {

"application/json": {

"schema": {

"$ref": "#/components/schemas/V2Error"

}

}

}

},

"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"

}

}

}

},

"ClientClosedRequest": {

"description": "The client closed the connection before the response was produced.",

"content": {

"application/json": {

"schema": {

"$ref": "#/components/schemas/V2Error"

}

}

}

},

"InternalError": {

"description": "An unexpected server error occurred.",

"content": {

"application/json": {

"schema": {

"$ref": "#/components/schemas/V2Error"

}

}

}

},

"ServiceUnavailable": {

"description": "A required service is temporarily unavailable.",

"content": {

"application/json": {

"schema": {

"$ref": "#/components/schemas/V2Error"

}

}

}

}

},

"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": "Optional structured error details."

}

},

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

}

}

]

},

"V2LogListItem": {

"type": "object",

"properties": {

"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", "redacting", "completed", "failed", "cancelled"],

"description": "Current execution status. `redacting` is transient while run output is scrubbed."

},

"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 unavailable."

},

"files": {

"anyOf": [

{

"type": "array",

"items": {

"description": "Attachment metadata captured for the execution."

}

},

{

"type": "null"

}

],

"description": "Files attached to the run, or null when none are recorded."

},

"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": [

"runId",

"workflowId",

"deploymentVersionId",

"status",

"level",

"trigger",

"startedAt",

"endedAt",

"totalDurationMs",

"cost",

"files"

],

"additionalProperties": false,

"title": "Execution log summary",

"description": "Summary information for one workflow execution log."

},

"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": "Legacy span duration in milliseconds."

},

"durationMs": {

"type": "number",

"description": "Span duration in milliseconds."

},

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

},

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

}

},

"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` to continue, and stop when it is null. Most v2 lists page, so null means the last page was reached. A few are full-set lists that return their whole bounded result in one response and therefore always report null; those say so in the operation description. Either way, null means there is nothing further to fetch — never construct a cursor yourself."

}

},

"required": ["data", "nextCursor"],

"additionalProperties": false,

"title": "Log list response",

"description": "A cursor-paginated page of workflow execution logs.",

"examples": [

{

"data": [

{

"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.0032

},

"files": null

}

],

"nextCursor": "eyJzdGFydGVkQXQiOiIyMDI2LTAxLTE1VDEwOjMwOjAwMFoifQ=="

}

]

},

"V2LogDetail": {