Skip to main content
GET
/
api
/
workflows
/
{id}
/
runs
List workflow run history
curl --request GET \
  --url https://app.puffle.ai/api/workflows/{id}/runs \
  --header 'Authorization: Bearer <token>'
{
  "runs": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "workflow_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "parent_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "status": "<string>",
      "started_at": "2023-11-07T05:31:56Z",
      "completed_at": "2023-11-07T05:31:56Z",
      "created_at": "2023-11-07T05:31:56Z",
      "workflow_run_steps": [
        {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "node_id": "<string>",
          "status": "<string>",
          "started_at": "2023-11-07T05:31:56Z",
          "completed_at": "2023-11-07T05:31:56Z",
          "error_message": "<string>"
        }
      ],
      "signal_entities": {
        "canonical_name": "<string>",
        "domain": "<string>"
      }
    }
  ]
}

​
Overview

Return the top-level run history for a workflow (parent_run_id IS NULL), newest first, with workflow_run_steps and linked signal_entities inlined. For step-level detail of a single run, pass ?run_id=<uuid>&include_steps=true — the response shape switches to { steps: [] }.

​
AI agent notes

Two response shapes. Without run_id + include_steps, you get { runs: [] }. With both, you get { steps: [] }. Check which based on your query.Pagination. Default limit is 50, capped at 100. Pages are 1-indexed via page. There’s no cursor — offset-based.Signal entity. Each run links to the signal entity that triggered it (if any) — canonical_name and domain. Null when the run was triggered manually or the entity was deleted.Related: Get a workflow.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
id
string<uuid>
required

Workflow UUID.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

Query Parameters

​
run_id
string<uuid>

When combined with include_steps=true, returns only the step detail for this run id.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
​
include_steps
enum<string>

Set true with run_id to fetch step detail in { steps: [] } shape.

Available options:
true,
false
​
page
string

1-indexed page. Defaults to 1.

​
limit
string

Page size. Defaults to 50, capped at 100.

Response

Either { runs: [] } (default, paginated list) or { steps: [] } (when run_id + include_steps=true).

​
runs
object[]
required