---
title: "Search Workflow Runs"
method: POST
path: "/v2/workflow-runs/search"
tags: ["Workflow Run API"]
---

# Search Workflow Runs

`POST /v2/workflow-runs/search`

Search workflow runs with filters. Supports filtering by workflow ID, status, user IDs, time range, linked ticket, and parent_workflow_run_id. To investigate a run's sub-workflows, search with parent_workflow_run_id set to that run's id (combine with statuses=[FAILED] to find failing children), then recurse into each child run.

## Request body

- SvflowPublicapiSearchWorkflowRunsRequest
  - `teamId` string — The ID of the team. Required.
  - `workflowId` string, nullable — Filter by workflow ID.
  - `statuses` SvflowCommonModelsWorkflowRunStatus[] — Filter by statuses (multiple allowed).
  - `targetUserId` string, nullable — Filter by the target user for the workflow run.
  - `initiatedByUserId` string, nullable — Filter by the user who initiated the workflow run.
  - `createdAfter` string, nullable — Filter by runs created after this timestamp (RFC3339 format).
  - `createdBefore` string, nullable — Filter by runs created before this timestamp (RFC3339 format).
  - `linkedTicketId` string, nullable — Filter by linked ticket ID.
  - `pageSize` integer, nullable — Maximum number of results to return. Default is 50, maximum is 200. Larger values are silently coerced server-side; the actual value used is returned in the X-Served-Page-Size response header.
  - `pageToken` string, nullable — Token for pagination. Leave empty for the first request.
  - `includeOutput` boolean, nullable — When true (default), each returned run includes its `output` field (the full workflow result). For multi-row search responses this can be megabytes per row — set to false if you only need run metadata; you can then fetch full output per-run via GetWorkflowRun. Strongly recommended `false` for any caller that does not need `output`.
  - `parentWorkflowRunId` string, nullable — Filter to the direct child runs (sub-workflows) of this parent run. Pass a run ID here to list the runs it spawned one level deep; combine with `statuses` (e.g. FAILED) to find the failing children.

## Response `200`

Success

- SvflowPublicapiSearchWorkflowRunsResponse
  - `data` SvflowPubapimodelsWorkflowRun[] — The list of workflow runs.
    - `id` string — The unique ID of the workflow run. Persist this to follow up with GetWorkflowRun / AwaitWorkflowRunResult. This is the orchestration (Temporal) run ID — the same identifier returned by the webhook trigger response and by the worker SDK as `ctx.currentWorkflowRun.id`.
    - `workflowId` string — The ID of the workflow that was run.
    - `teamId` string — The ID of the team that the workflow belongs to.
    - `status` 'WORKFLOW_RUN_STATUS_UNSPECIFIED' | 'WORKFLOW_RUN_STATUS_PENDING' | 'WORKFLOW_RUN_STATUS_RUNNING' | 'WORKFLOW_RUN_STATUS_COMPLETED' | 'WORKFLOW_RUN_STATUS_FAILED' | 'WORKFLOW_RUN_STATUS_DENIED' | 'WORKFLOW_RUN_STATUS_CANCELED'
    - `createdAt` string — The timestamp when the workflow run was created.
    - `completedAt` string, nullable — The timestamp when the workflow run completed (if applicable).
    - `initiatedByUserId` string — The ID of the user who initiated the workflow run.
    - `targetUserId` string, nullable — The ID of the target user for the workflow run (if different from initiator).
    - `inputs` string, nullable — The inputs provided to the workflow (JSON string).
    - `output` string, nullable — The output of the workflow run (JSON string, available when completed or failed).
    - `linkedTicketId` string, nullable — The ID of the linked ticket, if any.
    - `approvalRequestId` string, nullable — The ID of the approval request associated with this workflow run, if any.
    - `statusUpdatedAt` string — The timestamp when the workflow run status was last updated.
    - `parentWorkflowRunId` string, nullable — The run ID of the parent workflow run that spawned this run, if this run is a child (sub-workflow). Empty for top-level runs.
    - `parentWorkflowRunStepNumber` union — The step number in the parent run that spawned this run, if this run is a child.
      - integer
      - string, int64
  - `nextPageToken` string, nullable — Token for retrieving the next page of results. Empty if no more results.

## Other responses

- `default` — Error

---

[API](https://skmtc.net/serval/apis/serval-public-api.md) · [All operations](https://skmtc.net/serval/apis/serval-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/serval/serval-public-api/versions/0549515e9384/schema)