Sign in
Events

List change feed events

List this organization's change feed, ordered and resumable by cursor.

Scope: org-global by default — one ordered sequence across every namespace and resource type. An X-Namespace header (or namespace_id query param) narrows it to one namespace's events. Events recorded before namespace stamping shipped (2026-08) carry no namespace and are excluded by ANY namespace filter — a namespace-filtered read is not a replay of history older than that.

A consumer can be killed mid-stream and resume from its last stored next_cursor without re-reading or missing anything, as long as it resumes within the 90-day retention window — events older than that are permanently expired, not archived. A consumer that has been down longer than 90 days must resync current state instead of resuming.

A cursor is only meaningful for a FIXED filter set: it encodes a position in this organization's overall sequence, not a position within any particular namespace_id/event_type filter. Changing either filter mid-stream while reusing an old cursor silently skips whatever the previous filter combination would have matched in between — start a fresh cursor (or none) whenever the filters change.

High-churn event types (object.* under active storage syncs) can bury sparse ones thousands of pages deep in the unfiltered walk — a consumer looking for one type should pass event_type rather than walking everything.

get/v1/events

Query parameters

cursorstring nullable

Opaque cursor from a prior response's next_cursor. Omit to start from the beginning of the 90-day retention window.

Opaque cursor from a prior response's next_cursor. Omit to start from the beginning of the 90-day retention window.

next_cursorstring nullable

Alias for cursor — the response surfaces this name, so feeding it back must work. If both are given, cursor wins.

Alias for cursor — the response surfaces this name, so feeding it back must work. If both are given, cursor wins.

afterstring nullable

Alias for cursor. If both are given, cursor wins.

Alias for cursor. If both are given, cursor wins.

namespace_idstring nullable

Filter to events scoped to one namespace (ns_ id or name). The X-Namespace header does the same; if both are present they must agree.

Filter to events scoped to one namespace (ns_ id or name). The X-Namespace header does the same; if both are present they must agree.

event_type'object.created' | 'objects.created.batch' | 'object.updated' | 'object.deleted' | 'document.created' | 'document.updated' | 'document.deleted' | 'documents.updated.batch' | 'documents.deleted.batch' | 'collection.created' | 'collection.updated' | 'collection.deleted' | 'collection.documents.written' | 'collection.documents.batch_completed' | 'cluster.created' | 'cluster.updated' | 'cluster.deleted' | 'cluster.execution.started' | 'cluster.execution.completed' | 'cluster.execution.failed' | 'trigger.created' | 'trigger.updated' | 'trigger.deleted' | 'trigger.paused' | 'trigger.resumed' | 'trigger.fired' | 'trigger.execution.completed' | 'trigger.execution.failed' | 'taxonomy.created' | 'taxonomy.updated' | 'taxonomy.deleted' | 'alert.created' | 'alert.updated' | 'alert.deleted' | 'alert.triggered' | 'alert.execution.completed' | 'alert.execution.failed' | 'annotation.created' | 'annotation.updated' | 'annotation.deleted'

Webhook event types for real-time notifications.

These events are emitted when significant state changes occur in the system. Webhooks subscribe to specific event types and receive notifications via configured channels (email, Slack, HTTP webhooks).

Event Naming Convention: {resource}.{action}[.{sub-resource}[.{sub-action}]]

Examples: - object.created: New object ingested - collection.documents.written: Documents indexed - cluster.execution.completed: Cluster job finished

Cache Invalidation Annotations: Each event type includes a comment indicating recommended cache invalidation scope: - [KEY] = Invalidate specific document/object keys - [COLLECTION] = Invalidate collection-level cache - [NAMESPACE] = Invalidate namespace-level cache

Event Categories: - Object Lifecycle: Events for individual objects (create, update, delete) - Collection Lifecycle: Events for collections (create, update, delete, documents written) - Cluster Lifecycle: Events for clusters (create, update, delete, execution status) - Trigger Lifecycle: Events for cluster triggers (create, update, fire, execution status) - Taxonomy Lifecycle: Events for taxonomies (create, update, delete)

Use Cases: - Real-time sync with external systems - Audit trail and compliance logging - Automated workflows triggered by state changes - Cache invalidation for distributed systems - Notifications to team members via Slack/email

Filter to one event type.

limitinteger nullable

Page size (default 100).

Page size (default 100).

page_sizeinteger nullable

Alias for limit. If both are given, limit wins.

Alias for limit. If both are given, limit wins.

Response

Successful Response

next_cursorstring nullable

Pass as cursor on the next call to resume after these results. Unchanged from the request's cursor when this page was empty.

has_moreboolean required

Whether another page is available beyond this one.

Changes

Changed in 4 of the 29 revisions of this API.110

  • 27f74c951c4d17See the full diff
    • ▲

      for the query request parameter limit, default value 100 was removed

      request-parameter-default-value-removed

    • ○

      the endpoint scheme security BearerAuth AND NamespaceHeader was added to the API

      api-security-added

    • ○

      the endpoint scheme security BearerAuth was removed from the API

      api-security-removed

    • ○

      added the new optional query request parameter after

      new-optional-request-parameter

    • ○

      added the new optional query request parameter next_cursor

      new-optional-request-parameter

    • ○

      added the new optional query request parameter page_size

      new-optional-request-parameter

    • ○

      query request parameter limit list-of-types was widened by adding types null

      request-parameter-list-of-types-widened

    • ○

      for the query request parameter limit, the type/format was generalized from integer/ to /

      request-parameter-type-generalized

  • 5307993e44d31See the full diff
    • ○

      added the enum value collection.documents.batch_completed to the property anyOf[subschema #1: WebhookEventType]/ of the query request parameter event_type

      request-parameter-property-enum-value-added

  • 5d4c905106b41See the full diff
    • ○

      the endpoint scheme security BearerAuth was added to the API

      api-security-added

    This revision also has 3 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • fdb4bdd01a641See the full diff
    • ○

      endpoint added

      endpoint-added