> ## Documentation Index > Fetch the complete documentation index at: https://docs.firedrill.run/llms.txt > Use this file to discover all available pages before exploring further. # Stream authenticated browser progress and frames > Requires run.read and an Authorization bearer token, re-authenticated and re-authorized on each poll. text/event-stream events are browser-event (BrowserEvent JSON, id is its sequence), browser-frame (BrowserFrame JSON, no id), and browser-run (HostedBrowserRun JSON, no id). Closes at terminal state or after 25 seconds. Reconnect with after equal to the last browser-event id; Last-Event-ID alone is not consumed. Frames may repeat and are ephemeral. Authentication failures after streaming begins terminate the stream; canonical JSON errors apply only before response headers. No token query parameters are accepted. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/projects/{projectId}/browser-runs/{runId}/stream openapi: 3.1.0 info: title: Firedrill Control API version: 1.0.0 description: >- The control plane for drills, drill runs, and the worlds they run in. Errors always carry the canonical envelope; unsafe operations require an Idempotency-Key; long work returns an operation resource. servers: - url: https://api.firedrill.run security: - controlCredential: [] tags: - name: authentication description: Sessions, CLI exchange, credentials, and verification keys. x-group: Authentication - name: organizations description: Organization members, billing, usage, retention, audit, and exports. x-group: Organizations - name: projects description: Project lifecycle, access, grants, and repository bindings. x-group: Projects - name: builds description: Immutable builds, uploads, source drafts, and world definitions. x-group: Builds and source - name: tools description: Project Tool discovery, approval, source, and revocation. x-group: Tool library - name: worlds description: >- Managed environments, world sessions, state, time, reset, faults, forks, and snapshots. x-group: Environments and sessions - name: runs description: >- Hosted runs, comparisons, attachments, reports, evidence bundles, sharing, and exports. x-group: Runs and evidence - name: browser description: Managed browser tests, runs, messages, streams, frames, and artifacts. x-group: Browser testing - name: callbacks description: Callback receiver approval, revocation, and signing material. x-group: Callbacks - name: github-ci description: >- GitHub installations, repository automation, CI suites, cases, evidence, and checks. x-group: GitHub and CI - name: authoring description: Authoring sessions, proposals, turns, and scenario proposals. x-group: Cloud authoring paths: /v1/projects/{projectId}/browser-runs/{runId}/stream: get: tags: - browser summary: Stream authenticated browser progress and frames description: >- Requires run.read and an Authorization bearer token, re-authenticated and re-authorized on each poll. text/event-stream events are browser-event (BrowserEvent JSON, id is its sequence), browser-frame (BrowserFrame JSON, no id), and browser-run (HostedBrowserRun JSON, no id). Closes at terminal state or after 25 seconds. Reconnect with after equal to the last browser-event id; Last-Event-ID alone is not consumed. Frames may repeat and are ephemeral. Authentication failures after streaming begins terminate the stream; canonical JSON errors apply only before response headers. No token query parameters are accepted. operationId: browserRuns.stream parameters: - name: projectId in: path required: true schema: type: string pattern: ^prj_[0-9a-z]{12,32}$ - name: runId in: path required: true schema: type: string pattern: ^brun_[a-z0-9]{12,64}$ - name: after in: query required: false schema: type: integer minimum: 0 default: 0 responses: '200': description: >- SSE stream with a typed JSON data value per event, not one JSON response envelope content: text/event-stream: schema: oneOf: - $ref: '#/components/schemas/BrowserEvent' - $ref: '#/components/schemas/BrowserFrame' - $ref: '#/components/schemas/HostedBrowserRun' examples: progress: value: >+ id: 1 event: browser-event data: {"sequence":1,"type":"log","message":"Browser started","elapsedMs":0} '400': description: Canonical error envelope content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Canonical error envelope content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '403': description: Canonical error envelope content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: Canonical error envelope content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '409': description: Canonical error envelope content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Canonical error envelope content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' default: description: Canonical error envelope content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' components: schemas: BrowserEvent: type: object properties: sequence: type: integer minimum: 1 maximum: 1000 type: type: string message: type: string elapsedMs: type: number minimum: 0 required: - sequence - type - message - elapsedMs additionalProperties: false BrowserFrame: type: object properties: mediaType: type: string base64: type: string maxLength: 1048576 capturedAtMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - mediaType - base64 - capturedAtMs additionalProperties: false HostedBrowserRun: type: object properties: schemaVersion: type: number enum: - 1 runId: type: string pattern: ^brun_[a-z0-9]{12,64}$ sourceRunId: type: string pattern: ^brun_[a-z0-9]{12,64}$ organizationId: type: string projectId: type: string testId: type: string pattern: ^btest_[a-z0-9]{12,64}$ testVersion: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 definition: type: object properties: schemaVersion: type: number enum: - 1 id: type: string pattern: ^[A-Za-z0-9][A-Za-z0-9._-]{0,95}$ title: type: string minLength: 1 maxLength: 200 startUrl: type: string maxLength: 4000 format: uri task: type: string minLength: 1 maxLength: 20000 steps: default: [] maxItems: 500 type: array items: anyOf: - type: object properties: action: type: string enum: - navigate url: type: string minLength: 1 maxLength: 4000 required: - action - url additionalProperties: false - type: object properties: action: type: string enum: - click selector: anyOf: - type: object properties: by: type: string enum: - role role: type: string enum: - button - link - textbox - checkbox - radio - combobox - option - heading - alert - status - tab - menuitem name: type: string minLength: 1 maxLength: 4000 required: - by - role - name additionalProperties: false - type: object properties: by: type: string enum: - label value: type: string minLength: 1 maxLength: 4000 required: - by - value additionalProperties: false - type: object properties: by: type: string enum: - text value: type: string minLength: 1 maxLength: 4000 required: - by - value additionalProperties: false - type: object properties: by: type: string enum: - testId value: type: string minLength: 1 maxLength: 4000 required: - by - value additionalProperties: false - type: object properties: by: type: string enum: - css value: type: string minLength: 1 maxLength: 4000 required: - by - value additionalProperties: false required: - action - selector additionalProperties: false - type: object properties: action: type: string enum: - fill selector: anyOf: - type: object properties: by: type: string enum: - role role: type: string enum: - button - link - textbox - checkbox - radio - combobox - option - heading - alert - status - tab - menuitem name: type: string minLength: 1 maxLength: 4000 required: - by - role - name additionalProperties: false - type: object properties: by: type: string enum: - label value: type: string minLength: 1 maxLength: 4000 required: - by - value additionalProperties: false - type: object properties: by: type: string enum: - text value: type: string minLength: 1 maxLength: 4000 required: - by - value additionalProperties: false - type: object properties: by: type: string enum: - testId value: type: string minLength: 1 maxLength: 4000 required: - by - value additionalProperties: false - type: object properties: by: type: string enum: - css value: type: string minLength: 1 maxLength: 4000 required: - by - value additionalProperties: false value: type: string maxLength: 20000 parameter: type: string pattern: ^[A-Za-z0-9][A-Za-z0-9._-]{0,95}$ required: - action - selector additionalProperties: false - type: object properties: action: type: string enum: - press selector: anyOf: - type: object properties: by: type: string enum: - role role: type: string enum: - button - link - textbox - checkbox - radio - combobox - option - heading - alert - status - tab - menuitem name: type: string minLength: 1 maxLength: 4000 required: - by - role - name additionalProperties: false - type: object properties: by: type: string enum: - label value: type: string minLength: 1 maxLength: 4000 required: - by - value additionalProperties: false - type: object properties: by: type: string enum: - text value: type: string minLength: 1 maxLength: 4000 required: - by - value additionalProperties: false - type: object properties: by: type: string enum: - testId value: type: string minLength: 1 maxLength: 4000 required: - by - value additionalProperties: false - type: object properties: by: type: string enum: - css value: type: string minLength: 1 maxLength: 4000 required: - by - value additionalProperties: false key: type: string minLength: 1 maxLength: 80 required: - action - selector - key additionalProperties: false - type: object properties: action: type: string enum: - wait milliseconds: type: integer minimum: 0 maximum: 10000 required: - action - milliseconds additionalProperties: false assertions: default: [] maxItems: 100 type: array items: anyOf: - type: object properties: id: type: string pattern: ^[A-Za-z0-9][A-Za-z0-9._-]{0,95}$ kind: type: string enum: - visible selector: anyOf: - type: object properties: by: type: string enum: - role role: type: string enum: - button - link - textbox - checkbox - radio - combobox - option - heading - alert - status - tab - menuitem name: type: string minLength: 1 maxLength: 4000 required: - by - role - name additionalProperties: false - type: object properties: by: type: string enum: - label value: type: string minLength: 1 maxLength: 4000 required: - by - value additionalProperties: false - type: object properties: by: type: string enum: - text value: type: string minLength: 1 maxLength: 4000 required: - by - value additionalProperties: false - type: object properties: by: type: string enum: - testId value: type: string minLength: 1 maxLength: 4000 required: - by - value additionalProperties: false - type: object properties: by: type: string enum: - css value: type: string minLength: 1 maxLength: 4000 required: - by - value additionalProperties: false expected: default: true type: boolean required: - id - kind - selector - expected additionalProperties: false - type: object properties: id: type: string pattern: ^[A-Za-z0-9][A-Za-z0-9._-]{0,95}$ kind: type: string enum: - text selector: anyOf: - type: object properties: by: type: string enum: - role role: type: string enum: - button - link - textbox - checkbox - radio - combobox - option - heading - alert - status - tab - menuitem name: type: string minLength: 1 maxLength: 4000 required: - by - role - name additionalProperties: false - type: object properties: by: type: string enum: - label value: type: string minLength: 1 maxLength: 4000 required: - by - value additionalProperties: false - type: object properties: by: type: string enum: - text value: type: string minLength: 1 maxLength: 4000 required: - by - value additionalProperties: false - type: object properties: by: type: string enum: - testId value: type: string minLength: 1 maxLength: 4000 required: - by - value additionalProperties: false - type: object properties: by: type: string enum: - css value: type: string minLength: 1 maxLength: 4000 required: - by - value additionalProperties: false expected: type: string maxLength: 20000 contains: default: false type: boolean required: - id - kind - selector - expected - contains additionalProperties: false - type: object properties: id: type: string pattern: ^[A-Za-z0-9][A-Za-z0-9._-]{0,95}$ kind: type: string enum: - value selector: anyOf: - type: object properties: by: type: string enum: - role role: type: string enum: - button - link - textbox - checkbox - radio - combobox - option - heading - alert - status - tab - menuitem name: type: string minLength: 1 maxLength: 4000 required: - by - role - name additionalProperties: false - type: object properties: by: type: string enum: - label value: type: string minLength: 1 maxLength: 4000 required: - by - value additionalProperties: false - type: object properties: by: type: string enum: - text value: type: string minLength: 1 maxLength: 4000 required: - by - value additionalProperties: false - type: object properties: by: type: string enum: - testId value: type: string minLength: 1 maxLength: 4000 required: - by - value additionalProperties: false - type: object properties: by: type: string enum: - css value: type: string minLength: 1 maxLength: 4000 required: - by - value additionalProperties: false expected: type: string maxLength: 20000 required: - id - kind - selector - expected additionalProperties: false - type: object properties: id: type: string pattern: ^[A-Za-z0-9][A-Za-z0-9._-]{0,95}$ kind: type: string enum: - url expected: type: string minLength: 1 maxLength: 4000 required: - id - kind - expected additionalProperties: false required: - schemaVersion - id - startUrl - steps - assertions additionalProperties: false mode: type: string enum: - replay - agent interactive: type: boolean capture: type: object properties: screenshot: default: 'off' type: string enum: - 'off' - always - retain-on-failure video: default: 'off' type: string enum: - 'off' - always - retain-on-failure trace: default: 'off' type: string enum: - 'off' - always - retain-on-failure required: - screenshot - video - trace additionalProperties: false captureConsent: type: string enum: - include-sensitive-content captureMask: maxItems: 32 type: array items: anyOf: - type: object properties: by: type: string enum: - role role: type: string enum: - button - link - textbox - checkbox - radio - combobox - option - heading - alert - status - tab - menuitem name: type: string minLength: 1 maxLength: 4000 required: - by - role - name additionalProperties: false - type: object properties: by: type: string enum: - label value: type: string minLength: 1 maxLength: 4000 required: - by - value additionalProperties: false - type: object properties: by: type: string enum: - text value: type: string minLength: 1 maxLength: 4000 required: - by - value additionalProperties: false - type: object properties: by: type: string enum: - testId value: type: string minLength: 1 maxLength: 4000 required: - by - value additionalProperties: false - type: object properties: by: type: string enum: - css value: type: string minLength: 1 maxLength: 4000 required: - by - value additionalProperties: false state: type: string enum: - queued - running - passed - failed - completed - cancelled worldVerified: type: boolean worldBinding: type: object properties: hostedRunId: type: string pattern: ^hrun_[0-9a-z]{12,32}$ expectedRevision: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 packageId: type: string minLength: 1 maxLength: 255 sessionId: type: string minLength: 1 maxLength: 255 actorId: type: string minLength: 1 maxLength: 255 interactionId: type: string minLength: 1 maxLength: 255 buildHash: type: string pattern: ^sha256:[0-9a-f]{64}$ required: - hostedRunId - expectedRevision - packageId - sessionId - actorId - interactionId - buildHash additionalProperties: false worldVerification: type: object properties: state: type: string enum: - pending - verified - failed - cancelled evidenceBundleId: type: string minLength: 1 maxLength: 255 verdict: type: string enum: - passed - failed - inconclusive required: - state additionalProperties: false version: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 createdAtMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 updatedAtMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 startedAtMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 finishedAtMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 cancelRequestedAtMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 error: type: object properties: code: type: string message: type: string required: - code - message additionalProperties: false result: type: object additionalProperties: {} artifact: type: object properties: bytes: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 sha256: type: string pattern: ^[0-9a-f]{64}$ mediaType: type: string enum: - application/gzip expiresAtMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - bytes - sha256 - mediaType additionalProperties: false required: - schemaVersion - runId - organizationId - projectId - definition - mode - interactive - state - worldVerified - version - createdAtMs - updatedAtMs additionalProperties: false ErrorEnvelope: type: object properties: code: type: string pattern: ^(control|world)\.[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$ message: type: string minLength: 1 correlationId: type: string minLength: 1 retryable: type: boolean retryAfterMs: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 operationId: type: string source: type: string enum: - platform - simulated_provider issues: type: array items: type: object properties: path: type: string code: type: string message: type: string required: - path - code - message additionalProperties: false details: type: object propertyNames: type: string additionalProperties: {} evidence: type: object properties: sessionId: type: string runId: type: string journalSeq: type: integer minimum: 0 maximum: 9007199254740991 buildHash: type: string additionalProperties: false required: - code - message - correlationId - retryable - source additionalProperties: true securitySchemes: controlCredential: type: http scheme: bearer description: Opaque control credential ````