Skip to content
Try for free
On this page

Logs

List 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`.

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

Send a personal or workspace API key in X-API-Key. See key types and access; operations that reject workspace keys say so in their description.

Send X-API-Key in the request header.

Alternatively

Send a Sim OAuth access token in Authorization: Bearer. See OAuth authentication and scopes.

Authorization: Bearer YOUR_ACCESS_TOKEN

Required scopes: api:read

OAuth flows
json
{
  "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"
    }
  }
}

OAuth scope: api:read.

Query parameters

workspaceIdstringRequired

Workspace whose execution logs should be returned.

minLength
1
maxLength
128
workflowIdsstring

Comma-separated workflow identifiers to include. An empty entry is rejected. At most 200 entries.

triggersstring

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.

levelstring

Severity level to include.

enum
["info","error"]
startDatestring

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.

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))$
endDatestring

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.

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))$
minDurationMsinteger

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.

minimum
0
maximum
2147483647
maxDurationMsinteger

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.

minimum
0
maximum
2147483647
minCostnumber

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.

minimum
0
maximum
1000000
maxCostnumber

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.

minimum
0
maximum
1000000
modelstring

AI model used during execution.

detailsstring

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.

default
basic
enum
["basic","full"]
includeTraceSpansboolean

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.

includeFinalOutputboolean

Whether to include the final workflow output. Implies details=full, so the workflow summary is present regardless of what details is set to.

limitinteger

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.

default
100
cursorstring

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.

minLength
1
includeHandledErrorsboolean

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.

statusstring

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.

workflowNamestring

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.

minLength
1
maxLength
200
includeJobRunsboolean

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.

runIdstring

Exact run identifier to match.

minLength
1
maxLength
128
pattern
^[A-Za-z0-9._:-]+$
sortBystring

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.

default
startedAt
enum
["startedAt","durationMs","cost","status"]
sortOrderstring

Sort direction.

default
desc
enum
["asc","desc"]
folderPathsstring

Comma-separated workflow folder paths, including descendants. Up to 100 paths. Unknown folder paths contribute no matches.

Responses

200

A page of execution logs matching the filters.

object

A cursor-paginated page of workflow execution logs.

2 fields
dataarrayRequired

Items in the current page.

Schema details
Array itemobject

Summary information for one workflow execution log.

16 fields
kindstringRequired

Whether the run executed a workflow or a Chat / Sim-agent job. Job runs appear only when includeJobRuns=true.

enum
["workflow","job"]
runIdstringRequired

Unique run identifier.

workflowIdvalueRequired

Workflow identifier, or null when unavailable.

Schema details

Any of

Option 1string
Option 2null
deploymentVersionIdvalueRequired

Deployment version identifier, or null when unavailable.

Schema details

Any of

Option 1string
Option 2null
statusstringRequired

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.

enum
["pending","running","paused","redacting","completed","failed","cancelled"]
levelstringRequired

Log severity level.

triggerstringRequired

Trigger that started the run.

startedAtstringRequired

ISO 8601 execution start timestamp.

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))$
endedAtvalueRequired

ISO 8601 execution end timestamp, or null while the run is active.

Schema details

Any of

Option 1string
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))$
Option 2null
totalDurationMsvalueRequired

Total execution duration in milliseconds, or null while unavailable.

Schema details

Any of

Option 1number
Option 2null
costvalueRequired

Cost charged for the run, or null when the run has neither a recorded total nor an itemized ledger.

Schema details

Any of

Option 1object
1 field
totalnumberRequired

Total execution cost in USD.

Additional properties are not allowed.

Option 2null
filesvalueRequired

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.

Schema details

Any of

Option 1array
Schema details
Array itemobject

A file produced by the run this log records.

5 fields
idstringRequired

Identifier to address this file by on the download endpoint.

namestringRequired

File name, including its extension.

sizeintegerRequired

File size in bytes.

minimum
0
maximum
9007199254740991
typestringRequired

MIME type recorded for the file.

downloadPathstringRequired

Path to fetch this file's bytes from, relative to the API host.

Additional properties are not allowed.

Option 2null
hasHandledErrorsbooleanRequired

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.

workflowobject

Workflow summary for a full-detail result.

4 fields
idvalueRequired

Workflow identifier, or null when unavailable.

Schema details

Any of

Option 1string
Option 2null
namestringRequired

Workflow name.

descriptionvalueRequired

Workflow description, or null when unset.

Schema details

Any of

Option 1string
Option 2null
deletedbooleanRequired

Whether the workflow has been deleted.

Additional properties are not allowed.

finalOutputvalue

Final workflow output.

traceSpansarray

Block-level execution trace spans.

Schema details
Array itemobject

One recursive operation span in a workflow execution trace.

20 fields
idstringRequired

Trace-span identifier.

namestringRequired

Trace-span name.

typestringRequired

Trace-span category.

durationnumber

Current trace-span duration in milliseconds.

durationMsnumber

Compatibility field for span duration in milliseconds. Read duration for current trace spans.

startTimestring

ISO 8601 span start timestamp.

endTimestring

ISO 8601 span end timestamp.

statusstring

Trace-span status.

errorHandledboolean

Whether the recorded error was handled.

errorTypestring

Recorded error type.

errorMessagestring

Recorded error message.

blockIdstring

Workflow block associated with the span.

inputvalue

Input captured for the traced operation.

outputvalue

Output captured for the traced operation.

tokensvalue

Token usage attributed to the span.

Schema details

Any of

Option 1number

Total tokens attributed to the span.

Option 2object
3 fields
totalnumber

Total tokens.

inputnumber

Input tokens.

outputnumber

Output tokens.

Additional properties are not allowed.

costobject

Cost attributed to the span.

4 fields
totalnumber

Total span cost in USD.

inputnumber

Input-token cost in USD.

outputnumber

Output-token cost in USD.

toolCostnumber

Tool cost in USD.

Additional properties are not allowed.

relativeStartMsnumber

Offset from the root span in milliseconds.

contentWithheldboolean

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.

const
true
toolCallsarray

Tool calls recorded by the span.

Schema details
Array itemobject
8 fields
idstring

Tool-call identifier.

namestring

Invoked tool name.

argumentsvalue

Arguments supplied to the tool call.

resultvalue

Value returned by the tool call.

errorstring

Tool-call error message.

startTimestring

ISO 8601 tool-call start timestamp.

endTimestring

ISO 8601 tool-call end timestamp.

durationnumber

Tool-call duration in milliseconds.

Additional propertiesvalue

Additional provider-specific tool-call metadata.

childrenarray

Nested child trace spans.

Schema details

Array item references recursive schema LogTraceSpan. See the complete schema in the OpenAPI download.

Additional propertiesvalue

Additional provider-specific trace-span metadata.

Additional properties are not allowed.

nextCursorvalueRequired

Opaque cursor for the next page. Send it back as cursor; null means there are no more pages. Do not construct a cursor yourself.

Schema details

Any of

Option 1string
Option 2null

Additional properties are not allowed.

Response example 1

json
{
  "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=="
}

Response headers

X-RateLimit-Limitinteger

Maximum requests allowed in the current window.

minimum
0
maximum
9007199254740991
X-RateLimit-Remaininginteger

Requests remaining in the current window.

minimum
0
maximum
9007199254740991
X-RateLimit-Resetstring

ISO 8601 timestamp when the current rate-limit window resets.

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))$
Was this helpful?
Suggest an edit