Skip to content
Try for free
On this page

Logs

Get log statistics

Get bucketed run counts, success rate, errors, and mean latency for the workspace and individual workflows. Query fields describe window selection and bucketing. Folder filters cover subtrees. 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/stats

Get bucketed run counts, success rate, errors, and mean latency for the workspace and individual workflows. Query fields describe window selection and bucketing. Folder filters cover subtrees. 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 statistics to summarize.

minLength
1
maxLength
128
workflowIdsstring

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

folderPathsstring

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

triggersstring

Comma-separated trigger types to include. An empty entry is rejected. The vocabulary is open, so an unrecognized member selects no runs; the literal all disables this filter.

levelstring

Severity level to include.

enum
["info","error"]
includeHandledErrorsboolean

Whether runs with a handled block error are counted as handledErrorRuns, and whether level=error also selects them. Off by default: counting them scans each run’s stored trace.

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

Number of equal time buckets to divide the window into, from 1 to 500. It is the ceiling on how many buckets a series carries: with includeEmpty=true exactly this many are returned, otherwise only the buckets holding at least one run. Buckets are never narrower than one minute, so on a short window the series extends past the end of the window rather than being compressed, and the trailing buckets are empty.

default
72
minimum
1
maximum
500
includeEmptystring

Whether buckets with no runs are included in every series. Off by default, so each series carries only the buckets that hold at least one run; set it to publish exactly segmentCount buckets per series, empty ones included. The listed spellings are the whole accepted vocabulary and are case-sensitive; any other value is rejected.

default
false
enum
["true","1","yes","on","y","enabled","false","0","no","off","n","disabled"]

Responses

200

Bucketed execution statistics for the workspace.

object

Bucketed success rate, error count, and latency for a workspace and its workflows.

1 field
dataobjectRequired

Response data.

9 fields
workflowsarrayRequired

Per-workflow series, ordered by error rate descending then by name, capped at 200 entries.

Schema details
Array itemobject

Bucketed run counts and success rate for one workflow.

6 fields
workflowIdstringRequired

Workflow identifier, or the literal deleted for the single series that collects runs whose workflow no longer exists.

workflowNamestringRequired

Workflow name, or Deleted Workflow.

segmentsarrayRequired

Buckets in time order. Only the buckets with at least one run unless includeEmpty was set, in which case every bucket appears, empty ones included.

Schema details
Array itemobject

Run counts and mean latency for one time bucket.

4 fields
timestampstringRequired

ISO 8601 start of the bucket.

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

Runs that started inside the bucket.

successfulExecutionsnumberRequired

Runs in the bucket that did not error.

avgDurationMsnumberRequired

Mean duration of the bucket's runs in milliseconds, weighted by run count. Zero when no run in the bucket recorded a duration.

Additional properties are not allowed.

totalExecutionsnumberRequired

Runs for this workflow across the window.

totalSuccessfulnumberRequired

Runs for this workflow that did not error.

overallSuccessRatenumberRequired

Percentage of runs that did not error, from 0 to 100. 100 when there were no runs.

Additional properties are not allowed.

workflowsTruncatedbooleanRequired

Whether workflows was cut to 200 entries. The workspace totals and aggregateSegments are computed from every workflow before the cut, so they stay exact either way.

aggregateSegmentsarrayRequired

Workspace-wide totals per bucket, in time order. Subject to the same includeEmpty rule as each workflow series: empty buckets are omitted unless asked for.

Schema details
Array itemobject

Run counts and mean latency for one time bucket.

4 fields
timestampstringRequired

ISO 8601 start of the bucket.

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

Runs that started inside the bucket.

successfulExecutionsnumberRequired

Runs in the bucket that did not error.

avgDurationMsnumberRequired

Mean duration of the bucket's runs in milliseconds, weighted by run count. Zero when no run in the bucket recorded a duration.

Additional properties are not allowed.

totalRunsnumberRequired

Runs in the window across the whole workspace.

totalErrorsnumberRequired

Runs in the window that errored.

handledErrorRunsnumber

Runs in the window in which a block errored and was recovered by an error path. Such runs count as successful in every other figure. Present only when includeHandledErrors=true.

avgLatencynumberRequired

Mean run duration in milliseconds across the window, weighted by run count.

timeBoundsobjectRequired

Actual window; supplied bounds are exact. Without endDate, the right edge is the later of now and the newest matching run. Without startDate, the left edge is the oldest match, or 24 hours before the right edge when no runs match. With no matches or supplied bounds, this is the trailing 24 hours; endDate alone uses the preceding 24 hours, while startDate alone spans through now.

2 fields
startstringRequired

ISO 8601 start of the window.

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

ISO 8601 end of the window.

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.

segmentMsnumberRequired

Bucket width in milliseconds: max(60000, floor(windowMs / segmentCount)). The one-minute minimum applies to bucket width, not window width; when it applies, trailing empty buckets extend past timeBounds.end instead of compressing the window.

Additional properties are not allowed.

Additional properties are not allowed.

Response example 1

json
{
  "data": {
    "workflows": [
      {
        "workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
        "workflowName": "Customer Support Agent",
        "segments": [
          {
            "timestamp": "2026-01-15T10:00:00.000Z",
            "totalExecutions": 40,
            "successfulExecutions": 38,
            "avgDurationMs": 1180
          }
        ],
        "totalExecutions": 40,
        "totalSuccessful": 38,
        "overallSuccessRate": 95
      }
    ],
    "workflowsTruncated": false,
    "aggregateSegments": [
      {
        "timestamp": "2026-01-15T10:00:00.000Z",
        "totalExecutions": 40,
        "successfulExecutions": 38,
        "avgDurationMs": 1180
      }
    ],
    "totalRuns": 40,
    "totalErrors": 2,
    "avgLatency": 1180,
    "timeBounds": {
      "start": "2026-01-15T10:00:00.000Z",
      "end": "2026-01-15T22:00:00.000Z"
    },
    "segmentMs": 600000
  }
}

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