Forgeling Core developer docs

Events

Every event has the same envelope, and the shape of its data depends on its type.

Envelope

Field Type Required Description
id string yes
type string yes The event type. Clients ignore types they do not know.
created_at string yes When the API ingested the event, never the sandbox's clock.
api_version any yes
workspace object or null yes The workspace of the event; null for bundle.* and ping.
stream object or null yes The stream of the event; null for workspace., bundle. and ping.
turn_id string or null yes The turn the event belongs to, if any.
source platform | sandbox yes
repo_policy require_push_block | allow_unprotected no Present only on runs that set it.
metadata object no Present only when turn_id is set: the turn's metadata, echoed as the app sent it.
data object yes The payload; its schema is events/<type>.json. 
{
  "id": "evt_01M6GZ6ETT6VX39K33DX8RJJW8",
  "type": "turn.completed",
  "created_at": "2026-11-03T15:07:14.650Z",
  "api_version": "2026-11-01",
  "workspace": {
    "id": "ws_01M6GYS6C059AAC83G7BWCMBMM",
    "external_id": "org_42"
  },
  "stream": {
    "type": "run",
    "id": "run_01M6GYS6C0XNXDF714KDYE7SQ2",
    "seq": 17
  },
  "turn_id": "trn_01M6GYX5AG286S66P8BN33DBV3",
  "source": "sandbox",
  "metadata": {
    "stage": "implement"
  },
  "data": {
    "turn_id": "trn_01M6GYX5AG286S66P8BN33DBV3",
    "idempotency_key": "sf-42-implement-1",
    "status": "completed",
    "stop_reason": "end_turn",
    "output": {
      "text": "Added single sign-on login and opened the pull request."
    },
    "result": {
      "pr_url": "https://github.com/acme/shop/pull/42"
    },
    "result_error": null,
    "usage": {
      "model": "claude-sonnet-4-5",
      "input_tokens": 48210,
      "output_tokens": 6934,
      "cache_read_tokens": 212480,
      "cache_creation_tokens": 18340,
      "cost_usd": 0.412873
    },
    "metadata": {
      "stage": "implement"
    },
    "duration_ms": 303640
  }
}

JSON Schema of the envelope

Clients must ignore unknown fields, event types and enum values.

Run

run.queued

The run is waiting for capacity; position is its place in the queue.

Source: platform

Delivered by default: yes

Field Type Required Description
position integer yes Its place in the app's queue. 
{
  "id": "evt_01M6GYS6JPHBNTW2C0TCWBQ2ZE",
  "type": "run.queued",
  "created_at": "2026-11-03T15:00:00.214Z",
  "api_version": "2026-11-01",
  "workspace": {
    "id": "ws_01M6GYS6C059AAC83G7BWCMBMM",
    "external_id": "org_42"
  },
  "stream": {
    "type": "run",
    "id": "run_01M6GYS6C0XNXDF714KDYE7SQ2",
    "seq": 1
  },
  "turn_id": null,
  "source": "platform",
  "data": {
    "position": 2
  }
}

JSON Schema of the data

run.provisioning

Capacity was found and the run's sandbox is being prepared.

Source: platform

Delivered by default: yes

data is an empty object.

{
  "id": "evt_01M6GYTEWZV4SCRR5RVA74Z7JA",
  "type": "run.provisioning",
  "created_at": "2026-11-03T15:00:41.503Z",
  "api_version": "2026-11-01",
  "workspace": {
    "id": "ws_01M6GYS6C059AAC83G7BWCMBMM",
    "external_id": "org_42"
  },
  "stream": {
    "type": "run",
    "id": "run_01M6GYS6C0XNXDF714KDYE7SQ2",
    "seq": 2
  },
  "turn_id": null,
  "source": "platform",
  "data": {}
}

JSON Schema of the data

run.ready

The sandbox is up and its repositories are cloned, so the run can take turns; resources reports each repository's branch and head commit and whether the repository policy check passed or was allowed to fail.

Source: platform

Delivered by default: yes

Field Type Required Description
image_digest string yes The run image the run started on.
resources array of object yes 
{
  "id": "evt_01M6GYWKTQ4MY2MJ341YJM7MB7",
  "type": "run.ready",
  "created_at": "2026-11-03T15:01:52.087Z",
  "api_version": "2026-11-01",
  "workspace": {
    "id": "ws_01M6GYS6C059AAC83G7BWCMBMM",
    "external_id": "org_42"
  },
  "stream": {
    "type": "run",
    "id": "run_01M6GYS6C05Z8CJG26NDVEY1ZA",
    "seq": 3
  },
  "turn_id": null,
  "source": "platform",
  "repo_policy": "allow_unprotected",
  "data": {
    "image_digest": "sha256:cff1927e99d1301e5394bba2227de30ebad5b7fb2fa58ef7dd0b8e6522a00d89",
    "resources": [
      {
        "type": "git_repository",
        "path": "repo",
        "default_branch": "main",
        "branch": "story/sf-42/sso-login",
        "head_sha": "3bd14c7ceea57ec59c1f00ca4f020b8d25ee64dd",
        "branch_created": true,
        "repo_policy_check": "failed_allowed"
      }
    ]
  }
}

JSON Schema of the data

run.running

A turn was forwarded to a ready or idle run and the agent is working on it.

Source: platform

Delivered by default: yes

data is an empty object.

{
  "id": "evt_01M6GYX5YGFQPX2C8XEN31AFXP",
  "type": "run.running",
  "created_at": "2026-11-03T15:02:10.640Z",
  "api_version": "2026-11-01",
  "workspace": {
    "id": "ws_01M6GYS6C059AAC83G7BWCMBMM",
    "external_id": "org_42"
  },
  "stream": {
    "type": "run",
    "id": "run_01M6GYS6C0XNXDF714KDYE7SQ2",
    "seq": 4
  },
  "turn_id": null,
  "source": "platform",
  "data": {}
}

JSON Schema of the data

run.idle

The run finished its latest turn and is waiting for the next one; stop_reason says why the turn ended.

Source: platform

Delivered by default: yes

Field Type Required Description
stop_reason end_turn | budget_reached yes 
{
  "id": "evt_01M6GZ6F2P1PKN1WQAEBSFQWGN",
  "type": "run.idle",
  "created_at": "2026-11-03T15:07:14.902Z",
  "api_version": "2026-11-01",
  "workspace": {
    "id": "ws_01M6GYS6C059AAC83G7BWCMBMM",
    "external_id": "org_42"
  },
  "stream": {
    "type": "run",
    "id": "run_01M6GYS6C0XNXDF714KDYE7SQ2",
    "seq": 18
  },
  "turn_id": null,
  "source": "platform",
  "data": {
    "stop_reason": "end_turn"
  }
}

JSON Schema of the data

run.suspended

The run sat idle past its idle limit, so its sandbox was stopped; the disk is kept and the next turn resumes it.

Source: platform

Delivered by default: yes

data is an empty object.

{
  "id": "evt_01M6H0XD3EX6Y8PFPD5T8RZ65A",
  "type": "run.suspended",
  "created_at": "2026-11-03T15:37:15.118Z",
  "api_version": "2026-11-01",
  "workspace": {
    "id": "ws_01M6GYS6C059AAC83G7BWCMBMM",
    "external_id": "org_42"
  },
  "stream": {
    "type": "run",
    "id": "run_01M6GYS6C0XNXDF714KDYE7SQ2",
    "seq": 19
  },
  "turn_id": null,
  "source": "platform",
  "data": {}
}

JSON Schema of the data

run.resumed

A suspended run was brought back, just before its next turn is forwarded.

Source: platform

Delivered by default: yes

data is an empty object.

{
  "id": "evt_01M6H1RGXTXF6D8D0F3CSWKVD6",
  "type": "run.resumed",
  "created_at": "2026-11-03T15:52:03.770Z",
  "api_version": "2026-11-01",
  "workspace": {
    "id": "ws_01M6GYS6C059AAC83G7BWCMBMM",
    "external_id": "org_42"
  },
  "stream": {
    "type": "run",
    "id": "run_01M6GYS6C0XNXDF714KDYE7SQ2",
    "seq": 20
  },
  "turn_id": null,
  "source": "platform",
  "data": {}
}

JSON Schema of the data

run.completed

The run ended normally; usage_total adds up every turn and pushed_refs lists the refs the sandbox reports it pushed.

Source: platform

Delivered by default: yes

Field Type Required Description
usage_total Usage yes
pushed_refs array of PushedRef yes 
{
  "id": "evt_01M6H1YGX9BQ05B46TRCW7KR5C",
  "type": "run.completed",
  "created_at": "2026-11-03T15:55:20.361Z",
  "api_version": "2026-11-01",
  "workspace": {
    "id": "ws_01M6GYS6C059AAC83G7BWCMBMM",
    "external_id": "org_42"
  },
  "stream": {
    "type": "run",
    "id": "run_01M6GYS6C0XNXDF714KDYE7SQ2",
    "seq": 31
  },
  "turn_id": null,
  "source": "platform",
  "data": {
    "usage_total": {
      "model": "claude-sonnet-4-5",
      "input_tokens": 96420,
      "output_tokens": 13868,
      "cache_read_tokens": 212480,
      "cache_creation_tokens": 18340,
      "cost_usd": 0.825746
    },
    "pushed_refs": [
      {
        "ref": "refs/heads/story/sf-42/sso-login",
        "sha": "c045da53e4cc909f77d16a947acabe0736b1b2f9",
        "remote": "https://github.com/acme/shop",
        "at": "2026-11-03T15:54:41.009Z"
      }
    ]
  }
}

JSON Schema of the data

run.failed

The run ended with an error; code says why and message describes it.

Source: platform

Delivered by default: yes

Field Type Required Description
code capacity_unavailable | image_unavailable | infrastructure | credential_missing | repo_policy_unmet | repo_auth_failed | repo_not_found | ref_not_found | clone_failed | bootstrap_failed | events_lost | sandbox_protocol_violation yes
message string yes 
{
  "id": "evt_01M6GYZ85QMEJG0BW42EJR4J4N",
  "type": "run.failed",
  "created_at": "2026-11-03T15:03:18.455Z",
  "api_version": "2026-11-01",
  "workspace": {
    "id": "ws_01M6GYS6C059AAC83G7BWCMBMM",
    "external_id": "org_42"
  },
  "stream": {
    "type": "run",
    "id": "run_01M6GYS6C0XNXDF714KDYE7SQ2",
    "seq": 3
  },
  "turn_id": null,
  "source": "platform",
  "data": {
    "code": "clone_failed",
    "message": "The repository could not be cloned."
  }
}

JSON Schema of the data

run.cancelled

The run was cancelled before it completed.

Source: platform

Delivered by default: yes

data is an empty object.

{
  "id": "evt_01M6GZG69P5QHC1Q6KHGP3JH8B",
  "type": "run.cancelled",
  "created_at": "2026-11-03T15:12:33.590Z",
  "api_version": "2026-11-01",
  "workspace": {
    "id": "ws_01M6GYS6C059AAC83G7BWCMBMM",
    "external_id": "org_42"
  },
  "stream": {
    "type": "run",
    "id": "run_01M6GYS6C0XNXDF714KDYE7SQ2",
    "seq": 22
  },
  "turn_id": null,
  "source": "platform",
  "data": {}
}

JSON Schema of the data

run.expired

The run reached its lifetime limit or was evicted to free capacity; reason says which.

Source: platform

Delivered by default: yes

Field Type Required Description
reason lifetime | capacity_evicted yes 
{
  "id": "evt_01M6H271YRJF9TBJD68E6Q8027",
  "type": "run.expired",
  "created_at": "2026-11-03T15:59:59.960Z",
  "api_version": "2026-11-01",
  "workspace": {
    "id": "ws_01M6GYS6C059AAC83G7BWCMBMM",
    "external_id": "org_42"
  },
  "stream": {
    "type": "run",
    "id": "run_01M6GYS6C0XNXDF714KDYE7SQ2",
    "seq": 40
  },
  "turn_id": null,
  "source": "platform",
  "data": {
    "reason": "lifetime"
  }
}

JSON Schema of the data

Turn

turn.queued

The turn is waiting to be forwarded because the run is busy, resuming or short of capacity; reason says which.

Source: platform

Delivered by default: yes

Field Type Required Description
reason busy | resuming | capacity | null yes 
{
  "id": "evt_01M6GZ0K0C02WZNMXZ34G6K0DQ",
  "type": "turn.queued",
  "created_at": "2026-11-03T15:04:02.316Z",
  "api_version": "2026-11-01",
  "workspace": {
    "id": "ws_01M6GYS6C059AAC83G7BWCMBMM",
    "external_id": "org_42"
  },
  "stream": {
    "type": "run",
    "id": "run_01M6GYS6C0XNXDF714KDYE7SQ2",
    "seq": 9
  },
  "turn_id": "trn_01M6GYX5AG286S66P8BN33DBV3",
  "source": "platform",
  "metadata": {
    "stage": "implement"
  },
  "data": {
    "reason": "busy"
  }
}

JSON Schema of the data

turn.started

The agent began working on the turn.

Source: sandbox (validated by the platform; proves origin, not truth)

Delivered by default: yes

data is an empty object.

{
  "id": "evt_01M6GYX6AGT2XNAREXX9BRVNBJ",
  "type": "turn.started",
  "created_at": "2026-11-03T15:02:11.024Z",
  "api_version": "2026-11-01",
  "workspace": {
    "id": "ws_01M6GYS6C059AAC83G7BWCMBMM",
    "external_id": "org_42"
  },
  "stream": {
    "type": "run",
    "id": "run_01M6GYS6C0XNXDF714KDYE7SQ2",
    "seq": 5
  },
  "turn_id": "trn_01M6GYX5AG286S66P8BN33DBV3",
  "source": "sandbox",
  "metadata": {
    "stage": "implement"
  },
  "data": {}
}

JSON Schema of the data

turn.completed

The turn finished with an output and its usage, and with a structured result if the turn asked for one; treat result and cost_usd as agent-reported and re-check external state before any irreversible action.

Source: platform or sandbox (see source)

Delivered by default: yes

Field Type Required Description
turn_id string yes
idempotency_key string or null yes The Idempotency-Key the turn was posted with.
status any yes
stop_reason end_turn | budget_reached yes
output object yes
result any yes The value the agent submitted for the turn's output_schema; any JSON value, null when none was submitted.
result_error null | not_submitted | invalid yes Why result is null although the turn had an output_schema.
usage Usage yes
metadata object yes The turn's metadata, echoed as the app sent it.
duration_ms integer yes 
{
  "id": "evt_01M6GZ6ETT6VX39K33DX8RJJW8",
  "type": "turn.completed",
  "created_at": "2026-11-03T15:07:14.650Z",
  "api_version": "2026-11-01",
  "workspace": {
    "id": "ws_01M6GYS6C059AAC83G7BWCMBMM",
    "external_id": "org_42"
  },
  "stream": {
    "type": "run",
    "id": "run_01M6GYS6C0XNXDF714KDYE7SQ2",
    "seq": 17
  },
  "turn_id": "trn_01M6GYX5AG286S66P8BN33DBV3",
  "source": "sandbox",
  "metadata": {
    "stage": "implement"
  },
  "data": {
    "turn_id": "trn_01M6GYX5AG286S66P8BN33DBV3",
    "idempotency_key": "sf-42-implement-1",
    "status": "completed",
    "stop_reason": "end_turn",
    "output": {
      "text": "Added single sign-on login and opened the pull request."
    },
    "result": {
      "pr_url": "https://github.com/acme/shop/pull/42"
    },
    "result_error": null,
    "usage": {
      "model": "claude-sonnet-4-5",
      "input_tokens": 48210,
      "output_tokens": 6934,
      "cache_read_tokens": 212480,
      "cache_creation_tokens": 18340,
      "cost_usd": 0.412873
    },
    "metadata": {
      "stage": "implement"
    },
    "duration_ms": 303640
  }
}

JSON Schema of the data

turn.failed

The turn ended with an error; error carries a code and a message.

Source: platform or sandbox (see source)

Delivered by default: yes

Field Type Required Description
error object yes
usage null or Usage yes
duration_ms integer or null yes 
{
  "id": "evt_01M6GZ5D8RF7DJFFCX8SK493RN",
  "type": "turn.failed",
  "created_at": "2026-11-03T15:06:40.280Z",
  "api_version": "2026-11-01",
  "workspace": {
    "id": "ws_01M6GYS6C059AAC83G7BWCMBMM",
    "external_id": "org_42"
  },
  "stream": {
    "type": "run",
    "id": "run_01M6GYS6C0XNXDF714KDYE7SQ2",
    "seq": 12
  },
  "turn_id": "trn_01M6GYX5AG286S66P8BN33DBV3",
  "source": "sandbox",
  "metadata": {
    "stage": "implement"
  },
  "data": {
    "error": {
      "code": "model_error",
      "message": "The model returned an error."
    },
    "usage": {
      "model": "claude-sonnet-4-5",
      "input_tokens": 12044,
      "output_tokens": 388,
      "cache_read_tokens": 212480,
      "cache_creation_tokens": 18340,
      "cost_usd": 0.054112
    },
    "duration_ms": 61250
  }
}

JSON Schema of the data

turn.cancelled

The turn was cancelled before it finished; usage and duration_ms are null when it was cancelled before it ran.

Source: platform or sandbox (see source)

Delivered by default: yes

Field Type Required Description
usage null or Usage yes
duration_ms integer or null yes 
{
  "id": "evt_01M6GZ2D4NY39GV2VHJCNBADBT",
  "type": "turn.cancelled",
  "created_at": "2026-11-03T15:05:01.845Z",
  "api_version": "2026-11-01",
  "workspace": {
    "id": "ws_01M6GYS6C059AAC83G7BWCMBMM",
    "external_id": "org_42"
  },
  "stream": {
    "type": "run",
    "id": "run_01M6GYS6C0XNXDF714KDYE7SQ2",
    "seq": 11
  },
  "turn_id": "trn_01M6GYX5AG286S66P8BN33DBV3",
  "source": "platform",
  "metadata": {
    "stage": "implement"
  },
  "data": {
    "usage": null,
    "duration_ms": null
  }
}

JSON Schema of the data

turn.interrupted

The turn was cut off because its sandbox restarted or was lost; it is never run again.

Source: platform or sandbox (see source)

Delivered by default: yes

data is an empty object.

{
  "id": "evt_01M6GZAG6XR57H1ZSDEZPVE6ND",
  "type": "turn.interrupted",
  "created_at": "2026-11-03T15:09:27.133Z",
  "api_version": "2026-11-01",
  "workspace": {
    "id": "ws_01M6GYS6C059AAC83G7BWCMBMM",
    "external_id": "org_42"
  },
  "stream": {
    "type": "run",
    "id": "run_01M6GYS6C0XNXDF714KDYE7SQ2",
    "seq": 25
  },
  "turn_id": "trn_01M6GYX5AG286S66P8BN33DBV3",
  "source": "platform",
  "metadata": {
    "stage": "implement"
  },
  "data": {}
}

JSON Schema of the data

Agent output

message.completed

The agent finished a block of text; blocks arrive whole, never as partial deltas.

Source: sandbox (validated by the platform; proves origin, not truth)

Delivered by default: no

Field Type Required Description
text string yes Run secrets are redacted. 
{
  "id": "evt_01M6GYYVZMQB4501F4JT6KSG66",
  "type": "message.completed",
  "created_at": "2026-11-03T15:03:05.972Z",
  "api_version": "2026-11-01",
  "workspace": {
    "id": "ws_01M6GYS6C059AAC83G7BWCMBMM",
    "external_id": "org_42"
  },
  "stream": {
    "type": "run",
    "id": "run_01M6GYS6C0XNXDF714KDYE7SQ2",
    "seq": 7
  },
  "turn_id": "trn_01M6GYX5AG286S66P8BN33DBV3",
  "source": "sandbox",
  "metadata": {
    "stage": "implement"
  },
  "data": {
    "text": "The login test fails because the callback URL is not registered. I will fix the route first."
  }
}

JSON Schema of the data

tool.started

The agent called a tool; call_index pairs this event with its tool.completed event.

Source: sandbox (validated by the platform; proves origin, not truth)

Delivered by default: no

Field Type Required Description
call_index integer yes 1-based within the turn; pairs tool.started with tool.completed.
name string yes
input_summary string yes At most 16 KiB. Run secrets are redacted. 
{
  "id": "evt_01M6GYYWDAA27Q5CSRG9S05T2S",
  "type": "tool.started",
  "created_at": "2026-11-03T15:03:06.410Z",
  "api_version": "2026-11-01",
  "workspace": {
    "id": "ws_01M6GYS6C059AAC83G7BWCMBMM",
    "external_id": "org_42"
  },
  "stream": {
    "type": "run",
    "id": "run_01M6GYS6C0XNXDF714KDYE7SQ2",
    "seq": 8
  },
  "turn_id": "trn_01M6GYX5AG286S66P8BN33DBV3",
  "source": "sandbox",
  "metadata": {
    "stage": "implement"
  },
  "data": {
    "call_index": 1,
    "name": "Bash",
    "input_summary": "npm test -- --run auth"
  }
}

JSON Schema of the data

tool.completed

A tool call finished; summary holds at most 16 KiB and run secrets are redacted from it.

Source: sandbox (validated by the platform; proves origin, not truth)

Delivered by default: no

Field Type Required Description
call_index integer yes 1-based within the turn; pairs tool.started with tool.completed.
name string yes
is_error boolean yes
summary string yes At most 16 KiB. Run secrets are redacted.
duration_ms integer yes 
{
  "id": "evt_01M6GYZ4ME1T9H3CYDFDHDKHNZ",
  "type": "tool.completed",
  "created_at": "2026-11-03T15:03:14.830Z",
  "api_version": "2026-11-01",
  "workspace": {
    "id": "ws_01M6GYS6C059AAC83G7BWCMBMM",
    "external_id": "org_42"
  },
  "stream": {
    "type": "run",
    "id": "run_01M6GYS6C0XNXDF714KDYE7SQ2",
    "seq": 9
  },
  "turn_id": "trn_01M6GYX5AG286S66P8BN33DBV3",
  "source": "sandbox",
  "metadata": {
    "stage": "implement"
  },
  "data": {
    "call_index": 1,
    "name": "Bash",
    "is_error": false,
    "summary": "Tests: 11 passed, 1 failed (auth/callback.test.ts)",
    "duration_ms": 8420
  }
}

JSON Schema of the data

Approvals

approval.requested

The agent asked to use a tool that the run does not pre-approve; the request expires at expires_at and is then denied.

Source: sandbox (validated by the platform; proves origin, not truth)

Delivered by default: yes

Field Type Required Description
approval_id string yes
tool string yes
input_summary string yes At most 16 KiB. Run secrets are redacted.
expires_at string yes When the request lapses unanswered. 
{
  "id": "evt_01M6GZ2BERM3X0XHEK0V3Q4WCR",
  "type": "approval.requested",
  "created_at": "2026-11-03T15:05:00.120Z",
  "api_version": "2026-11-01",
  "workspace": {
    "id": "ws_01M6GYS6C059AAC83G7BWCMBMM",
    "external_id": "org_42"
  },
  "stream": {
    "type": "run",
    "id": "run_01M6GYS6C0XNXDF714KDYE7SQ2",
    "seq": 13
  },
  "turn_id": "trn_01M6GYX5AG286S66P8BN33DBV3",
  "source": "sandbox",
  "metadata": {
    "stage": "implement"
  },
  "data": {
    "approval_id": "apr_01M6GZ2BB0PGEMWZPTFY467KS3",
    "tool": "Bash",
    "input_summary": "git push origin story/sf-42/sso-login",
    "expires_at": "2026-11-03T15:20:00.120Z"
  }
}

JSON Schema of the data

approval.resolved

An approval was allowed, denied or expired; reason tells a decision from an expiry.

Source: platform

Delivered by default: yes

Field Type Required Description
approval_id string yes
decision allow | deny yes
reason decided | expired yes
note string or null yes 
{
  "id": "evt_01M6GZ3MYJSE5JPHG2HP2TNS51",
  "type": "approval.resolved",
  "created_at": "2026-11-03T15:05:42.610Z",
  "api_version": "2026-11-01",
  "workspace": {
    "id": "ws_01M6GYS6C059AAC83G7BWCMBMM",
    "external_id": "org_42"
  },
  "stream": {
    "type": "run",
    "id": "run_01M6GYS6C0XNXDF714KDYE7SQ2",
    "seq": 14
  },
  "turn_id": "trn_01M6GYX5AG286S66P8BN33DBV3",
  "source": "platform",
  "metadata": {
    "stage": "implement"
  },
  "data": {
    "approval_id": "apr_01M6GZ2BB0PGEMWZPTFY467KS3",
    "decision": "allow",
    "reason": "decided",
    "note": "Push to the story branch is fine."
  }
}

JSON Schema of the data

Outputs and spend

output.created

A file the agent wrote to the run's outputs was collected; file is the file object.

Source: platform

Delivered by default: yes

Field Type Required Description
file File yes 
{
  "id": "evt_01M6GZ9P574653X2H18FQ87798",
  "type": "output.created",
  "created_at": "2026-11-03T15:09:00.455Z",
  "api_version": "2026-11-01",
  "workspace": {
    "id": "ws_01M6GYS6C059AAC83G7BWCMBMM",
    "external_id": "org_42"
  },
  "stream": {
    "type": "run",
    "id": "run_01M6GYS6C0XNXDF714KDYE7SQ2",
    "seq": 24
  },
  "turn_id": null,
  "source": "platform",
  "data": {
    "file": {
      "id": "file_01M6GZ9NQ0MQQJNZ7HH80PPPFA",
      "object": "file",
      "run": "run_01M6GYS6C0XNXDF714KDYE7SQ2",
      "workspace": "ws_01M6GYS6C059AAC83G7BWCMBMM",
      "path": "outputs/preview.webm",
      "size_bytes": 1843200,
      "sha256": "793ef691b2952eaefb4529fb0cb4ffdbbb31a3366f84af61111826db7b044a35",
      "content_type": "video/webm",
      "created_at": "2026-11-03T15:09:00.301Z",
      "expires_at": "2026-12-03T15:09:00.301Z",
      "status": "available"
    }
  }
}

JSON Schema of the data

budget.warning

The run has used 80 percent of its budget.

Source: platform

Delivered by default: yes

Field Type Required Description
max_cost_usd number yes
spent_usd number yes
threshold any yes 
{
  "id": "evt_01M6GZ4HQDRJB10R0P339AF43Y",
  "type": "budget.warning",
  "created_at": "2026-11-03T15:06:12.077Z",
  "api_version": "2026-11-01",
  "workspace": {
    "id": "ws_01M6GYS6C059AAC83G7BWCMBMM",
    "external_id": "org_42"
  },
  "stream": {
    "type": "run",
    "id": "run_01M6GYS6C0XNXDF714KDYE7SQ2",
    "seq": 15
  },
  "turn_id": null,
  "source": "platform",
  "data": {
    "max_cost_usd": 5.0,
    "spent_usd": 4.0,
    "threshold": 0.8
  }
}

JSON Schema of the data

secret.refresh_failed

The platform could not refresh a run secret through your credential-refresh endpoint; name is the secret and expires_at is when its current value stops working.

Source: platform

Delivered by default: yes

Field Type Required Description
name string yes
expires_at string yes 
{
  "id": "evt_01M6H1A0TJKXY67HSP9XQGBXEK",
  "type": "secret.refresh_failed",
  "created_at": "2026-11-03T15:44:08.530Z",
  "api_version": "2026-11-01",
  "workspace": {
    "id": "ws_01M6GYS6C059AAC83G7BWCMBMM",
    "external_id": "org_42"
  },
  "stream": {
    "type": "run",
    "id": "run_01M6GYS6C0XNXDF714KDYE7SQ2",
    "seq": 21
  },
  "turn_id": null,
  "source": "platform",
  "data": {
    "name": "GITHUB_TOKEN",
    "expires_at": "2026-11-03T15:50:00.000Z"
  }
}

JSON Schema of the data

Platform

workspace.credential_invalid

The workspace's model credential failed a check and is marked invalid; runs that need it cannot start until you replace it.

Source: platform

Delivered by default: yes

Field Type Required Description
type any yes
checked_at string yes 
{
  "id": "evt_01M6H0G46J433BS824T57V99XM",
  "type": "workspace.credential_invalid",
  "created_at": "2026-11-03T15:30:00.018Z",
  "api_version": "2026-11-01",
  "workspace": {
    "id": "ws_01M6GYS6C059AAC83G7BWCMBMM",
    "external_id": "org_42"
  },
  "stream": null,
  "turn_id": null,
  "source": "platform",
  "data": {
    "type": "anthropic_api_key",
    "checked_at": "2026-11-03T15:30:00.012Z"
  }
}

JSON Schema of the data

bundle.version_ready

A bundle version passed validation and new runs can use it.

Source: platform

Delivered by default: yes

Field Type Required Description
bundle string yes
version string yes 
{
  "id": "evt_01M6GZXYSVTXQ0B3TPBJMHFFMC",
  "type": "bundle.version_ready",
  "created_at": "2026-11-03T15:20:04.667Z",
  "api_version": "2026-11-01",
  "workspace": null,
  "stream": null,
  "turn_id": null,
  "source": "platform",
  "data": {
    "bundle": "specflow-dev",
    "version": "1.0.0"
  }
}

JSON Schema of the data

bundle.version_rejected

A bundle version failed validation; errors lists each problem with its path.

Source: platform

Delivered by default: yes

Field Type Required Description
bundle string yes
version string yes
errors array of object yes 
{
  "id": "evt_01M6GZZXTN8NFE2MF4BEAHB452",
  "type": "bundle.version_rejected",
  "created_at": "2026-11-03T15:21:09.205Z",
  "api_version": "2026-11-01",
  "workspace": null,
  "stream": null,
  "turn_id": null,
  "source": "platform",
  "data": {
    "bundle": "specflow-dev",
    "version": "1.1.0",
    "errors": [
      {
        "path": "mcp_servers[0].url",
        "message": "must be an https URL"
      }
    ]
  }
}

JSON Schema of the data

ping

A test event, sent when you call the endpoint test route, so you can check your receiver and its signature check.

Source: platform

Sent by POST /v1/webhook_endpoints/{id}/test

data is an empty object.

{
  "id": "evt_01M6H06Z734HHM8MVH8PYBNDJ7",
  "type": "ping",
  "created_at": "2026-11-03T15:25:00.003Z",
  "api_version": "2026-11-01",
  "workspace": null,
  "stream": null,
  "turn_id": null,
  "source": "platform",
  "data": {}
}

JSON Schema of the data