Skip to content
Try for free
On this page

Logs

Get log

Get a run's workflow graph, trace spans, final output, and cost. Trace spans expire separately, so an empty `traceSpans` array does not prove none were recorded. 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/{runId}

Get a run's workflow graph, trace spans, final output, and cost. Trace spans expire separately, so an empty traceSpans array does not prove none were recorded. 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.

Path parameters

runIdstringRequired

Unique workflow run identifier.

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

Query parameters

includeWorkflowStateboolean

Include the saved workflow snapshot (default: true). Set false to omit block configuration from a log read. Other run fields are unchanged.

Responses

200

The requested diagnostic log representation.

object

The complete diagnostic representation of a workflow run.

1 field
dataobjectRequired

Response data.

18 fields
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
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
executedByEmailvalueRequired

Email of the identity the run executed as: the caller for an interactive or personal-API-key run, and the workspace billing account for a schedule, webhook, deployed chat, or public API call. Null when the run failed before an identity was resolved.

Schema details

Any of

Option 1string
format
email
pattern
^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
Option 2null
workflowobjectRequired

Workflow snapshot associated with the execution.

9 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
folderPathvalueRequired

Canonical folder path of the workflow, in the same form folderPaths accepts as a filter: / for a workflow at the workspace root. Null only when the path cannot be resolved — the folder has been deleted, or the workflow itself no longer exists.

Schema details

Any of

Option 1string

Canonical slash-prefixed folder path. / is the workspace root. Segments are percent-encoded, so a folder shown as "New folder" is /New%20folder: everything outside A-Z a-z 0-9 - _ . ~ is escaped as uppercase hex, and only that exact encoding is accepted. A trailing slash, an empty segment, and a literal . or .. segment are rejected. At most 64 segments and 4096 encoded bytes.

maxLength
4096
Option 2null
ownerEmailvalueRequiredDeprecated

Deprecated — use the run-level executedByEmail instead. Email of the workflow's current owner, or null when unavailable. This is a property of the workflow as it stands today, not of the run: it changes when workflow ownership is reassigned, and the owner is not the identity a background run executes as.

Schema details

Any of

Option 1string
format
email
pattern
^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
Option 2null
workspaceIdvalueRequired

Owning workspace identifier, or null when unavailable.

Schema details

Any of

Option 1string
Option 2null
createdAtvalueRequired

ISO 8601 workflow creation timestamp, or null when unavailable.

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
updatedAtvalueRequired

ISO 8601 workflow update timestamp, or null when unavailable.

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
deletedbooleanRequired

Whether the workflow has been deleted.

Additional properties are not allowed.

workflowStatevalueRequired

Workflow graph captured for the run, or null if unavailable or includeWorkflowState=false. Sensitive values are redacted to null; environment-variable references may be preserved.

Schema details

Any of

Option 1object
Schema details
Additional propertiesvalue

One top-level snapshot section — blocks, edges, loops, parallels, or variables — passed through as stored.

Option 2null
traceSpansarrayRequired

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

finalOutputvalueRequired

Materialized final workflow output, or null when none was produced.

Schema details

Any of

Option 1value

Materialized final workflow output value.

Option 2null
costvalueRequired

Cost charged for the run, or null when unavailable.

Schema details

Any of

Option 1object
2 fields
totalnumberRequired

Total execution cost in USD.

itemsvalueRequired

Billed lines reconciling to total, or null when no itemized ledger exists for the run.

Schema details

Any of

Option 1array
Schema details
Array itemobject

One billed line of a run, folded across every event that billed it.

5 fields
categorystringRequired

What the line is for: the run's base fee (fixed), one model's inference (model), or one metered tool or integration call (tool).

enum
["fixed","model","tool"]
descriptionstringRequired

Human-readable name of the billed item, such as the model or tool id.

costnumberRequired

Amount billed for this line, in USD.

inputTokensnumber

Input tokens attributed to this line. Absent for lines that do not bill tokens.

outputTokensnumber

Output tokens attributed to this line. Absent for lines that do not bill tokens.

Additional properties are not allowed.

Option 2null

Additional properties are not allowed.

Option 2null
workflowInputvalueRequired

Input the run was triggered with, or null when the run recorded none. Credential-bearing and PII-masked values are redacted the same way finalOutput is.

Schema details

Any of

Option 1value

Caller-supplied trigger payload for the run.

Option 2null
createdAtstringRequired

ISO 8601 log creation 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))$

Additional properties are not allowed.

Additional properties are not allowed.

Response example 1

json
{
  "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,
    "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"
      }
    ],
    "executedByEmail": "billing@example.com",
    "workflow": {
      "id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
      "name": "Customer Support Agent",
      "description": "Routes incoming support tickets and drafts responses",
      "folderPath": "/",
      "ownerEmail": "jane@example.com",
      "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
      "createdAt": "2025-01-10T09:00:00.000Z",
      "updatedAt": "2025-06-18T16:45:00.000Z",
      "deleted": false
    },
    "workflowState": {
      "blocks": {},
      "edges": []
    },
    "traceSpans": [],
    "finalOutput": {
      "result": "Hello, world!"
    },
    "cost": {
      "total": 0.0072,
      "items": [
        {
          "category": "fixed",
          "description": "Base execution charge",
          "cost": 0.005
        },
        {
          "category": "model",
          "description": "gpt-5",
          "cost": 0.0022,
          "inputTokens": 1840,
          "outputTokens": 260
        }
      ]
    },
    "workflowInput": {
      "ticketId": "T-4821"
    },
    "createdAt": "2026-01-15T10:30:00.000Z"
  }
}

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