Skip to main content
GET
The reference panel describes the current v3 operation. The notes below describe its v2 compatibility API. Follow the v3 request schema for current calls: v3 can move identifiers from the body or query into the URL. Keep the v2 method, path, and payload together when using the compatibility API.

v2 compatibility notes

Webhooks notify; this endpoint is the source of truth. Deliveries are scheduled and retried independently and carry no sequence counter, so a receiver cannot tell from the delivery stream alone whether it missed something. GET /api/v2/events returns the same events out of the canonical log in insertion order behind an opaque cursor — which is what makes a gap detectable and recoverable.
Every event returned is a v2 envelope, the same shape a webhook delivery carries. The envelope’s id is the join key between the two surfaces. Every webhook’s id is readable here within the 30-day window: Forge does not deliver an event it could not write to this log.

Authentication

External App credential. Requires the events:read permission as the entry point — but holding it alone returns nothing. See Visibility below.

Query parameters

string
Opaque pagination token from a previous response’s nextCursor. Omit to start at the beginning of the retention window.Treat the value as opaque: its encoding is not part of the contract and may change. Round-trip it verbatim — do not parse, truncate, or reconstruct it. A cursor advances past the last row of the page you received, so paging with the cursor you were handed neither repeats nor skips a row.
Two events emitted in the same millisecond may straddle a page boundary. The cursor is stable across that boundary, but you must still deduplicate on each envelope’s id — that is the only identity guaranteed to be unique and stable across pages, replays, and webhook delivery.
string
Comma-separated event types to restrict the page to, e.g. workflow.completed,step.completed. Omit for every event visible to the caller.Filtering narrows the result set only — it never widens visibility. An event you have no scope for stays invisible whether or not you name its type.
number
Page size, 1 to 100. Defaults to 50. A value above 100 is 400 too_big; a non-integer is a 400.

Response

object[]
Events in insertion order, oldest first.
string | null
Cursor for the next page, in data.nextCursor (not meta), or null when the window is exhausted. A page is read first and filtered afterwards, so a short or empty page with a non-null cursor is normal: keep paging until the cursor is null. null means “you are caught up as of this read”, not “no more events will ever exist” — poll again later with the last non-null cursor you stored.
There is deliberately no sequence field on the envelope. A per-orderingKey counter would be a transactional write on the run or session row, putting every parallel branch of a workflow DAG into write contention for the same document. Ordering comes from paging this endpoint, not from a counter on the event.

Visibility

Three conditions, all required. Failing any one of them means the event is simply absent from your pages — there is no error, and no way to tell it existed.
1

Entry scope: the app holds events:read

Without it the request itself is a 403. This is the gate on the endpoint, not on any particular event.
2

Per-event scope: the app's roles cover that event's subscriptionScope

Each event type declares the catalog permissions required to see it — runs:read for workflow.* and step.*, audit:read, grants:read and policies:read for approval.*, and so on (the full map). An app with events:read and nothing else sees an empty log. "admin"-scoped events are operator-only and never appear here for any app, whatever scopes it holds.
3

Initiator match: the app caused the event

An app sees only events it initiated. This is the same predicate the webhook fan-out uses — one shared function, so the push surface and the pull surface cannot drift into disagreeing about what an app is allowed to see.
Scope is evaluated at read time against the scopes the app’s role grants cover, not at the time the event was emitted. Revoking a role retroactively hides matching events from this endpoint, including ones the app already received by webhook. Giving a role does not backfill visibility beyond the retention window.

Retention

The window is 30 days, matching webhook delivery retention. Events older than that are pruned and are not recoverable through this endpoint. An outage longer than the window is a data-loss event for your integration — alert on your reconciliation cursor falling behind long before it approaches 30 days.

Worked example: recovering from an outage

Your receiver was down from 02:00 to 06:00. Some deliveries were retried into your endpoint and failed; some dead-lettered. Rather than replaying each delivery, page the log forward from the last cursor you committed.
Your handler is a no-op when called twice with the same event.id. That single property is what turns at-least-once delivery plus a cursor walk into an exactly-once integration.

Errors

A non-integer limit, or a malformed cursor. A cursor from a different deployment or a hand-edited one lands here rather than silently returning the wrong window.
permission_denied: missing the events:read entry permission (named in error.requiredPermission). forbidden: the caller is not an External App. Note that an app with events:read but no per-event scopes gets 200 and an empty events array — not a 403.

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Query Parameters

cursor
string

Opaque nextCursor from a previous page; omit to start the window

limit
integer
default:50

Rows read per page, 1 to 100; a larger value is 400 too_big

Required range: 1 <= x <= 100
types
string

Comma-separated event types to keep, e.g. workflow.completed

Response

One page of the event log

data
object
required
meta
object
required

A list page's continuation. While hasMore is true, nextCursor is a string: pass it as cursor for the next page. hasMore: false ends the list; with truncated: true, more exist past what this list reads, and no cursor reaches them.