> ## Documentation Index
> Fetch the complete documentation index at: https://docs.julian.11x.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflow run API

> Start an API-triggered workflow, inspect a run, and page through run history.

Publish an **API request** workflow for the agent before using these endpoints. Its published Start API request node defines the JSON fields the POST accepts: up to 50 flat text, number, boolean, timestamp, or URL values. Field names use lower camelCase or snake\_case, start with a lowercase letter, contain at most 64 characters, and must be unique regardless of case.

Use your organization's API key in the `x-api-key` header on all three routes. HMAC signing headers are not required.

## Start a run

`POST https://julian.11x.ai/api/v1/workflows/{agentId}/run`

| Parameter | Location | Required | Description |
| - | - | - | - |
| `agentId` | Path | Yes | Agent that owns the published API request workflow. |
| `x-api-key` | Header | Yes | Organization API key for that agent. |
| JSON body | Body | Yes | Flat object matching the published input fields, including every required field. Unknown fields and nested values are rejected. |
| `Idempotency-Key` | Header | No | Unique key for one intended run; reuse it with the same body when retrying. Maximum 255 characters. |

```bash theme={}
curl -X POST "https://julian.11x.ai/api/v1/workflows/$AGENT_ID/run" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-request-001" \
  -d '{"contact_name":"Example Person","priority":2}'
```

A successful `201` returns `{ "workflowRunId": "wf-run.…" }`. Save that ID to read the run. Sending the same body and idempotency key again returns the same ID; reusing the key with a different body returns `422`. Without a key, each POST can start a new run. Invalid input returns `400`; an agent with no enabled published API workflow returns `404`. A `429` response includes `Retry-After`.

## Get one run

`GET https://julian.11x.ai/api/v1/workflows/{agentId}/run?runId={workflowRunId}`

| Parameter | Location | Required | Description |
| - | - | - | - |
| `agentId` | Path | Yes | Agent that owns the run. |
| `x-api-key` | Header | Yes | Organization API key for that agent. |
| `runId` | Query | Yes | `workflowRunId` returned by POST. |

```bash theme={}
curl "https://julian.11x.ai/api/v1/workflows/$AGENT_ID/run?runId=$WORKFLOW_RUN_ID" \
  -H "x-api-key: $API_KEY"
```

The `200` response includes `workflowRunId`, `status`, `startedAt`, `finishedAt`, and `terminalNodes`. Status is `queued`, `in_progress`, `completed`, or `failed`. `startedAt` is null until execution begins; `finishedAt` is null until it ends. Each terminal node includes its name and `succeeded` or `failed` status. A failed run still returns HTTP `200`; an unknown or inaccessible run returns `404`.

## List runs

`GET https://julian.11x.ai/api/v1/workflows/{agentId}/runs`

| Parameter | Location | Required | Description |
| - | - | - | - |
| `agentId` | Path | Yes | Agent whose API-triggered runs to list. |
| `x-api-key` | Header | Yes | Organization API key for that agent. |
| `cursor` | Query | No | Opaque `nextCursor` from the previous page. Omit it for the first page. |

```bash theme={}
curl "https://julian.11x.ai/api/v1/workflows/$AGENT_ID/runs" \
  -H "x-api-key: $API_KEY"
```

The response contains up to 50 newest-first summaries in `runs` and a `nextCursor`. Each summary includes the run ID, status, start time, and finish time. Pass a non-null `nextCursor` as `?cursor=<nextCursor>` for the next page; stop when it is null. History includes older API workflow bindings and excludes builder test runs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.