> ## Documentation Index > Fetch the complete documentation index at: https://usefoil.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # List events > List organization events. Requires Authorization: Bearer sk_* with the webhooks:read scope. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/organizations/{organizationId}/events openapi: 3.1.0 info: title: Foil API version: '2026-03-25' description: >- Customer-facing Foil server APIs for sessions, visitor fingerprints, organizations, and API keys. servers: - url: https://api.usefoil.com description: Production security: [] tags: - name: Sessions description: Durable session readback endpoints. - name: Visitor fingerprints description: Durable visitor fingerprint readback endpoints. - name: Organizations description: Organization lifecycle endpoints. - name: API Keys description: Organization API key lifecycle endpoints. - name: Gate description: >- Registry, organization-owned services, signup sessions, agent tokens, and dashboard login sessions. - name: Gate Webhooks description: Outbound Gate webhook delivery contracts. - name: Webhooks description: Manage webhook endpoints, subscriptions, and outgoing event delivery. - name: Events description: Inspect organization events and their webhook delivery attempts. paths: /v1/organizations/{organizationId}/events: get: tags: - Events summary: List events description: >- List organization events. Requires Authorization: Bearer sk_* with the webhooks:read scope. operationId: listEvents parameters: - name: organizationId in: path required: true schema: $ref: '#/components/schemas/OrganizationId' example: org_f6m39y94nh6fs513q03skj929c - name: endpoint_id in: query required: false description: >- Only return events that produced a delivery for this webhook endpoint. schema: $ref: '#/components/schemas/WebhookEndpointId' example: we_0123456789abcdef0123456789abcdef - name: type in: query required: false description: Only return events of this type. schema: $ref: '#/components/schemas/WebhookDeliveryEventType' example: session.fingerprint.calculated - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 200 default: 50 example: 50 responses: '200': description: Events. content: application/json: schema: $ref: '#/components/schemas/EventListResponse' example: data: - object: event id: wevt_0123456789abcdef0123456789abcdef type: session.fingerprint.calculated subject: type: type id: sid_87wfetm98myh9awj0dpt28a3kc data: source: signup_form webhook_deliveries: - object: webhook_delivery id: wdlv_0123456789abcdef0123456789abcdef event_id: wevt_0123456789abcdef0123456789abcdef endpoint_id: we_0123456789abcdef0123456789abcdef event_type: session.fingerprint.calculated status: pending attempts: 1 response_status: 1 response_body: response_body error: error created_at: '2026-03-24T20:00:00.000Z' updated_at: '2026-03-24T20:00:05.000Z' created_at: '2026-03-24T20:00:00.000Z' pagination: limit: 50 has_more: false next_cursor: >- eyJ2IjoxLCJzY29yZWRBdCI6IjIwMjYtMDQtMTBUMDY6NDI6NDIuNTE0WiIsInJvd0lkIjoiMTc3In0 meta: request_id: req_cf147349a4134208aebb8c70e25fb7e1 '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' example: error: code: request.validation_failed message: Observation payload failed validation. status: 1 retryable: true request_id: req_cf147349a4134208aebb8c70e25fb7e1 docs_url: https://app.acme.co/signup details: fields: - name: Acme Growth Workspace issue: required expected: string received: any_of allowed_values: - verified header_name: x-forwarded-for parameter_set: browser_fingerprint next_action: retry '403': description: Organization access denied or insufficient scope. content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' example: error: code: request.validation_failed message: Observation payload failed validation. status: 1 retryable: true request_id: req_cf147349a4134208aebb8c70e25fb7e1 docs_url: https://app.acme.co/signup details: fields: - name: Acme Growth Workspace issue: required expected: string received: any_of allowed_values: - verified header_name: x-forwarded-for parameter_set: browser_fingerprint next_action: retry '422': description: Invalid event list query. content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' example: error: code: request.validation_failed message: Observation payload failed validation. status: 1 retryable: true request_id: req_cf147349a4134208aebb8c70e25fb7e1 docs_url: https://app.acme.co/signup details: fields: - name: Acme Growth Workspace issue: required expected: string received: any_of allowed_values: - verified header_name: x-forwarded-for parameter_set: browser_fingerprint next_action: retry security: - BearerAuth: [] components: schemas: OrganizationId: type: string pattern: ^org_[0123456789abcdefghjkmnpqrstvwxyz]{26}$ example: org_f6m39y94nh6fs513q03skj929c WebhookEndpointId: type: string pattern: ^we_[0-9a-f]{32}$ example: we_0123456789abcdef0123456789abcdef WebhookDeliveryEventType: type: string enum: - session.fingerprint.calculated - session.result.persisted - gate.session.approved - webhook.test example: session.fingerprint.calculated EventListResponse: type: object additionalProperties: false required: - data - pagination - meta properties: data: type: array items: $ref: '#/components/schemas/Event' example: object: event id: wevt_0123456789abcdef0123456789abcdef type: session.fingerprint.calculated subject: type: type id: sid_87wfetm98myh9awj0dpt28a3kc data: source: signup_form webhook_deliveries: - object: webhook_delivery id: wdlv_0123456789abcdef0123456789abcdef event_id: wevt_0123456789abcdef0123456789abcdef endpoint_id: we_0123456789abcdef0123456789abcdef event_type: session.fingerprint.calculated status: pending attempts: 1 response_status: 1 response_body: response_body error: error created_at: '2026-03-24T20:00:00.000Z' updated_at: '2026-03-24T20:00:05.000Z' created_at: '2026-03-24T20:00:00.000Z' example: - object: event id: wevt_0123456789abcdef0123456789abcdef type: session.fingerprint.calculated subject: type: type id: sid_87wfetm98myh9awj0dpt28a3kc data: source: signup_form webhook_deliveries: - object: webhook_delivery id: wdlv_0123456789abcdef0123456789abcdef event_id: wevt_0123456789abcdef0123456789abcdef endpoint_id: we_0123456789abcdef0123456789abcdef event_type: session.fingerprint.calculated status: pending attempts: 1 response_status: 1 response_body: response_body error: error created_at: '2026-03-24T20:00:00.000Z' updated_at: '2026-03-24T20:00:05.000Z' created_at: '2026-03-24T20:00:00.000Z' pagination: $ref: '#/components/schemas/CursorPagination' example: limit: 50 has_more: false next_cursor: >- eyJ2IjoxLCJzY29yZWRBdCI6IjIwMjYtMDQtMTBUMDY6NDI6NDIuNTE0WiIsInJvd0lkIjoiMTc3In0 meta: $ref: '#/components/schemas/ResponseMeta' example: request_id: req_cf147349a4134208aebb8c70e25fb7e1 example: data: - object: event id: wevt_0123456789abcdef0123456789abcdef type: session.fingerprint.calculated subject: type: type id: sid_87wfetm98myh9awj0dpt28a3kc data: source: signup_form webhook_deliveries: - object: webhook_delivery id: wdlv_0123456789abcdef0123456789abcdef event_id: wevt_0123456789abcdef0123456789abcdef endpoint_id: we_0123456789abcdef0123456789abcdef event_type: session.fingerprint.calculated status: pending attempts: 1 response_status: 1 response_body: response_body error: error created_at: '2026-03-24T20:00:00.000Z' updated_at: '2026-03-24T20:00:05.000Z' created_at: '2026-03-24T20:00:00.000Z' pagination: limit: 50 has_more: false next_cursor: >- eyJ2IjoxLCJzY29yZWRBdCI6IjIwMjYtMDQtMTBUMDY6NDI6NDIuNTE0WiIsInJvd0lkIjoiMTc3In0 meta: request_id: req_cf147349a4134208aebb8c70e25fb7e1 ApiErrorEnvelope: type: object additionalProperties: false required: - error properties: error: $ref: '#/components/schemas/PublicError' example: code: request.validation_failed message: Observation payload failed validation. status: 1 retryable: true request_id: req_cf147349a4134208aebb8c70e25fb7e1 docs_url: https://app.acme.co/signup details: fields: - name: Acme Growth Workspace issue: required expected: string received: any_of allowed_values: - verified header_name: x-forwarded-for parameter_set: browser_fingerprint next_action: retry example: error: code: request.validation_failed message: Observation payload failed validation. status: 1 retryable: true request_id: req_cf147349a4134208aebb8c70e25fb7e1 docs_url: https://app.acme.co/signup details: fields: - name: Acme Growth Workspace issue: required expected: string received: any_of allowed_values: - verified header_name: x-forwarded-for parameter_set: browser_fingerprint next_action: retry Event: type: object additionalProperties: false required: - object - id - type - subject - data - webhook_deliveries - created_at properties: object: type: string const: event example: event id: $ref: '#/components/schemas/WebhookEventId' example: wevt_0123456789abcdef0123456789abcdef type: $ref: '#/components/schemas/WebhookDeliveryEventType' example: session.fingerprint.calculated subject: $ref: '#/components/schemas/EventSubject' example: type: type id: sid_87wfetm98myh9awj0dpt28a3kc data: type: object additionalProperties: true example: source: signup_form webhook_deliveries: type: array items: $ref: '#/components/schemas/WebhookDelivery' example: object: webhook_delivery id: wdlv_0123456789abcdef0123456789abcdef event_id: wevt_0123456789abcdef0123456789abcdef endpoint_id: we_0123456789abcdef0123456789abcdef event_type: session.fingerprint.calculated status: pending attempts: 1 response_status: 1 response_body: response_body error: error created_at: '2026-03-24T20:00:00.000Z' updated_at: '2026-03-24T20:00:05.000Z' example: - object: webhook_delivery id: wdlv_0123456789abcdef0123456789abcdef event_id: wevt_0123456789abcdef0123456789abcdef endpoint_id: we_0123456789abcdef0123456789abcdef event_type: session.fingerprint.calculated status: pending attempts: 1 response_status: 1 response_body: response_body error: error created_at: '2026-03-24T20:00:00.000Z' updated_at: '2026-03-24T20:00:05.000Z' created_at: type: string format: date-time example: '2026-03-24T20:00:00.000Z' example: object: event id: wevt_0123456789abcdef0123456789abcdef type: session.fingerprint.calculated subject: type: type id: sid_87wfetm98myh9awj0dpt28a3kc data: source: signup_form webhook_deliveries: - object: webhook_delivery id: wdlv_0123456789abcdef0123456789abcdef event_id: wevt_0123456789abcdef0123456789abcdef endpoint_id: we_0123456789abcdef0123456789abcdef event_type: session.fingerprint.calculated status: pending attempts: 1 response_status: 1 response_body: response_body error: error created_at: '2026-03-24T20:00:00.000Z' updated_at: '2026-03-24T20:00:05.000Z' created_at: '2026-03-24T20:00:00.000Z' CursorPagination: type: object additionalProperties: false required: - limit - has_more properties: limit: type: integer minimum: 1 maximum: 200 example: 50 has_more: type: boolean example: false next_cursor: type: string example: >- eyJ2IjoxLCJzY29yZWRBdCI6IjIwMjYtMDQtMTBUMDY6NDI6NDIuNTE0WiIsInJvd0lkIjoiMTc3In0 example: limit: 50 has_more: false next_cursor: >- eyJ2IjoxLCJzY29yZWRBdCI6IjIwMjYtMDQtMTBUMDY6NDI6NDIuNTE0WiIsInJvd0lkIjoiMTc3In0 ResponseMeta: type: object additionalProperties: false required: - request_id properties: request_id: $ref: '#/components/schemas/RequestId' example: req_cf147349a4134208aebb8c70e25fb7e1 example: request_id: req_cf147349a4134208aebb8c70e25fb7e1 PublicError: type: object additionalProperties: false required: - code - message - status - retryable - request_id properties: code: type: string x-foil-known-values-ref: '#/components/schemas/KnownPublicErrorCode' example: request.validation_failed message: type: string example: Observation payload failed validation. status: type: integer example: 1 retryable: type: boolean example: true request_id: $ref: '#/components/schemas/RequestId' example: req_cf147349a4134208aebb8c70e25fb7e1 docs_url: type: string format: uri example: https://app.acme.co/signup details: $ref: '#/components/schemas/ApiErrorDetails' example: fields: - name: Acme Growth Workspace issue: required expected: string received: any_of allowed_values: - verified header_name: x-forwarded-for parameter_set: browser_fingerprint next_action: retry example: code: request.validation_failed message: Observation payload failed validation. status: 1 retryable: true request_id: req_cf147349a4134208aebb8c70e25fb7e1 docs_url: https://app.acme.co/signup details: fields: - name: Acme Growth Workspace issue: required expected: string received: any_of allowed_values: - verified header_name: x-forwarded-for parameter_set: browser_fingerprint next_action: retry WebhookEventId: type: string pattern: ^wevt_[0-9a-f]{32}$ example: wevt_0123456789abcdef0123456789abcdef EventSubject: type: object additionalProperties: false required: - type - id properties: type: type: string example: type id: type: string example: sid_87wfetm98myh9awj0dpt28a3kc example: type: type id: sid_87wfetm98myh9awj0dpt28a3kc WebhookDelivery: type: object additionalProperties: false required: - object - id - event_id - endpoint_id - event_type - status - attempts - response_status - response_body - error - created_at - updated_at properties: object: type: string const: webhook_delivery example: webhook_delivery id: $ref: '#/components/schemas/WebhookDeliveryId' example: wdlv_0123456789abcdef0123456789abcdef event_id: $ref: '#/components/schemas/WebhookEventId' example: wevt_0123456789abcdef0123456789abcdef endpoint_id: $ref: '#/components/schemas/WebhookEndpointId' example: we_0123456789abcdef0123456789abcdef event_type: $ref: '#/components/schemas/WebhookDeliveryEventType' example: session.fingerprint.calculated status: $ref: '#/components/schemas/WebhookDeliveryStatus' example: pending attempts: type: integer minimum: 0 example: 1 response_status: type: - integer - 'null' example: 1 response_body: type: - string - 'null' example: response_body error: type: - string - 'null' example: error created_at: type: string format: date-time example: '2026-03-24T20:00:00.000Z' updated_at: type: string format: date-time example: '2026-03-24T20:00:05.000Z' example: object: webhook_delivery id: wdlv_0123456789abcdef0123456789abcdef event_id: wevt_0123456789abcdef0123456789abcdef endpoint_id: we_0123456789abcdef0123456789abcdef event_type: session.fingerprint.calculated status: pending attempts: 1 response_status: 1 response_body: response_body error: error created_at: '2026-03-24T20:00:00.000Z' updated_at: '2026-03-24T20:00:05.000Z' RequestId: type: string pattern: ^req_[0-9a-f]{32}$ example: req_cf147349a4134208aebb8c70e25fb7e1 ApiErrorDetails: type: object properties: fields: type: array items: $ref: '#/components/schemas/ApiFieldIssue' example: name: Acme Growth Workspace issue: required expected: string received: any_of example: - name: Acme Growth Workspace issue: required expected: string received: any_of allowed_values: type: array items: type: string example: verified example: - verified header_name: type: string example: x-forwarded-for parameter_set: type: string example: browser_fingerprint next_action: type: string enum: - retry - new_session - reload_bundle - contact_support example: retry additionalProperties: true example: fields: - name: Acme Growth Workspace issue: required expected: string received: any_of allowed_values: - verified header_name: x-forwarded-for parameter_set: browser_fingerprint next_action: retry WebhookDeliveryId: type: string pattern: ^wdlv_[0-9a-f]{32}$ example: wdlv_0123456789abcdef0123456789abcdef WebhookDeliveryStatus: type: string enum: - pending - delivering - succeeded - failed - skipped example: pending ApiFieldIssue: type: object additionalProperties: false required: - name - issue properties: name: type: string example: Acme Growth Workspace issue: type: string example: required expected: type: string example: string received: anyOf: - type: string example: '0' - type: number example: 1.5 - type: boolean example: true - type: 'null' example: null example: any_of example: name: Acme Growth Workspace issue: required expected: string received: any_of securitySchemes: BearerAuth: type: http scheme: bearer description: >- Send Authorization: Bearer . Gate business endpoints require sk_* secret keys. Gate workflow endpoints use gate-native bearer tokens such as gtpoll_* or agt_* where documented. ````