---
title: "Search runs by query (beta)"
method: POST
path: "/workflows/runs/query"
tags: ["workflowsRuns"]
---

# Search runs by query (beta)

`POST /workflows/runs/query`

## Request

- Base URL: `https://api.clay.com/public/v0`
- URL: `https://api.clay.com/public/v0/workflows/runs/query`
- Auth: API key in header `clay-api-key`

Execute a Clay workflow-run query. A `select` query returns matching runs newest-first with a `cursor` for the next page; a `count` query returns the number of matching runs. Get the query grammar with GET /workflows/runs/query/reference. Results are read from an eventually-consistent replica (replication lag is typically a few seconds), so a just-created or just-transitioned run may briefly be missing or show its prior status.

## Request body

- RunsQueryRequest
  - `cursor` string
  - `limit` integer
  - `query` string, required

## Response `200`

200

- union
  - RunsQuerySelectResponse
    - `cursor` string
    - `data` RunsQueryRow[], required
      - `action_credits_used` number, required
      - `created_at` string, required
      - `data_credits_used` number, required
      - `ended_at` string, nullable, required
      - `id` string, required
      - `input_field_count` integer, required
      - `output_field_count` integer, required
      - `run_status` string, required
      - `started_at` string, required
      - `trigger_fired_id` string, nullable
      - `trigger_id` string, nullable, required
      - `workflow_id` string, required
      - `workflow_snapshot_id` string, required
    - `mode` 'select', required
  - RunsQueryCountResponse
    - `count` integer, required
    - `mode` 'count', required

## Other responses

- `400`: 400
- `401`: 401
- `403`: 403
- `429`: 429

## Changes

- **2026-10-02** `6d313613a702`: 1 info
  - added the optional property `oneOf[#/components/schemas/RunsQuerySelectResponse]/data/items/trigger_fired_id` to the response with the `200` status
- **2026-09-09** `1ad1dc0d13b2`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/clay/apis/clay-public-api/changes/workflows/runs/query/post.md)

---

[API](https://skmtc.dev/clay/apis/clay-public-api.md) - [All operations](https://skmtc.dev/clay/apis/clay-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/clay/apis/clay-public-api/revisions/583f58ced7f1?raw)