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. Retention is 30 days from run start on Free, unlimited on Pro and Team, and configured per organization on Enterprise with workspace overrides. Workspace folder trees exceeding 10,000 folders return 413.

OAuth scope: api:read.

GET/api/v2/logs

Authorization

X-API-Key<token>

Your Sim API key, personal or workspace-scoped. Generate one under Settings, then API Keys. Operations that reject workspace keys say so in their own description.

In: header

Query Parameters

workspaceId*string

Workspace whose execution logs should be returned.

Length1 <= length <= 128
workflowIds?string

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

triggers?string

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.

level?string

Severity level to include.

Value in"info" | "error"
startDate?string

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.

Match^(?:(?:\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))$
Formatdate-time
endDate?string

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.

Match^(?:(?:\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))$
Formatdate-time
minDurationMs?integer

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.

Range0 <= value <= 2147483647
maxDurationMs?integer

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.

Range0 <= value <= 2147483647
minCost?number

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.

Range0 <= value <= 1000000
maxCost?number

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.

Range0 <= value <= 1000000
model?string

AI model used during execution.

details?string

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"
Value in"basic" | "full"
includeTraceSpans?boolean

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.

includeFinalOutput?boolean

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

limit?integer

Maximum log entries per page. Values outside 1–1000 are truncated and clamped into that range rather than rejected. Defaults to 100.

Default100
cursor?string

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.

Length1 <= length
status?string

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.

workflowName?string

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.

Length1 <= length <= 200
includeJobRuns?boolean

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.

runId?string

Exact run identifier to match.

Match^[A-Za-z0-9._:-]+$
Length1 <= length <= 128
sortBy?string

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"
Value in"startedAt" | "durationMs" | "cost" | "status"
sortOrder?string

Sort direction.

Default"desc"
Value in"asc" | "desc"
folderPaths?string

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

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://www.sim.ai/api/v2/logs?workspaceId=string" \  -H "X-API-Key: YOUR_API_KEY"
{
  "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.0032
      },
      "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=="
}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request"
  }
}
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}
{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient workspace permissions",
    "details": {
      "code": "INSUFFICIENT_WORKSPACE_ROLE"
    }
  }
}
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Not found"
  }
}
{
  "error": {
    "code": "PAYLOAD_TOO_LARGE",
    "message": "Request body is too large"
  }
}
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "API rate limit exceeded",
    "details": {
      "retryAfter": "2026-01-01T00:00:30.000Z"
    }
  }
}
{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error"
  }
}
{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service temporarily unavailable"
  }
}
GETGet Log StatisticsPOSTAdd Column