---
title: "Wait for an event"
method: POST
path: "/v1/runs/{runId}/wait"
tags: ["Events"]
---

# Wait for an event

`POST /v1/runs/{runId}/wait`

## Request

- Base URL: `https://api.ironfang.com/rig`
- URL: `https://api.ironfang.com/rig/v1/runs/{runId}/wait`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Blocks until an event after `since` matches, or the timeout passes. The wait reads the timeline first, so an event that already happened is answered at once, then wakes as new events land. A timeout is a 200 with `matched: false`, never an error: nothing went wrong, the thing has not happened yet, and `next_since` says where to continue. Timeouts are 1s to 90s (default 30s); loop with `next_since` for longer. `match` keys are top-level fields of the event's data: `field` compares as JSON, `field_contains` requires a string containing the value. Deterministic: the same timeline and request always answer the same event. At most 16 waits per organisation may be open at once.

## Request body

- object
  - `match` object
  - `resource` string: Limit to one of the run's resources, by name.
  - `since` integer: Consider only events with a greater sequence.
  - `timeout` string
  - `type` string, required

## Response `200`

Matched, or timed out without a match

- object
  - `event` Event
    - `blob_ref` string: Reference to a stored payload too large to embed.
    - `data` object, required
    - `id` string, uuid, required
    - `occurred_at` string, date-time, required: Ironfang's clock.
    - `organisation_id` string, uuid, required
    - `project_id` string, uuid, required
    - `resource_id` string, uuid
    - `run_id` string, uuid, required
    - `sequence` integer, required: The run's own counter, contiguous from 1.
    - `suite_id` string, uuid, required
    - `type` string, required
  - `matched` boolean, required
  - `next_since` integer, required: The last sequence examined; pass it as since to continue.
  - `waited_ms` integer, required

## Other responses

- `400`: The body is not one strict JSON value of the documented shape (`invalid_json`).
- `401`: No credential, an invalid one, or a delegated token where none is accepted (`unauthorized`, `invalid_api_key`, `delegated_not_allowed`).
- `403`: The credential lacks the permission or scope, or names another organisation (`forbidden`, `insufficient_scope`).
- `404`: No such object in this organisation (`not_found`).
- `422`: A field is invalid; the message names it (`invalid_request`).
- `429`: Too many waits are open for this organisation (`too_many_waiters`); retry after a moment.

---

[API](https://skmtc.dev/ironfang/apis/ironfang-rig-api.md) · [All operations](https://skmtc.dev/ironfang/apis/ironfang-rig-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ironfang/apis/ironfang-rig-api/revisions/3e86a312dad1?raw)