> ## Documentation Index > Fetch the complete documentation index at: https://docs.getoneprofile.ai/llms.txt > Use this file to discover all available pages before exploring further. # Stream a table's change events > Server-sent event stream of a table's changes: row cell deltas, run progress, and column / display-preference / row-set invalidation signals. Replaces the 2-second status poll — an idle table costs nothing. Deltas carry the row's `version`, the same watermark the rows list carries, so applying one twice or out of order is a no-op. There is deliberately NO replay log: clients refetch once on every connect, and a mid-stream gap is reported as a `resync` frame meaning the same thing. The server closes the stream after a few minutes with a `reconnect` frame; reconnect with a fresh token. Comment heartbeats keep intermediaries from dropping an idle connection. Requires Clerk authentication; API keys are rejected. There is deliberately no 404 — an unknown or foreign table streams heartbeats only, because the channel is org-scoped and leaks nothing. ## OpenAPI ````yaml /openapi.json get /tables/{table_id}/events/ openapi: 3.1.0 info: contact: email: support@getoneprofile.ai name: Oneprofile Support description: >- REST API reference for Oneprofile, the GTM data layer for your CRM. Manage tables, enrichments, and integrations. Authenticate with an API key to get started. termsOfService: https://www.getoneprofile.ai/terms title: API Reference | Oneprofile version: '0.0' servers: - url: https://api.getoneprofile.ai security: [] tags: - description: Sender profiles, connected mailboxes, tags, and the Google connect flow. name: senders - description: The workspace do-not-contact list, enforced before every send. name: suppression - description: 'Sequence authoring: the graph, the table-backed audience, previews.' name: sequences - description: >- The LinkedIn channel: connecting an account to a sender, its safety limits and history, and the protocol the browser extension speaks. name: linkedin - description: 'The unified outreach inbox: threads, replies, labels, events.' name: inbox - description: 'The AI reply layer: workspace settings, drafts, and approval.' name: inbox-ai - description: Notification rules, per-user preferences, and the Slack connection. name: notifications - description: Endpoints for seeing all available integration types. name: integration-types - description: Endpoints for creating and managing integrations. name: integrations - description: Endpoints for the generic OAuth install/claim app-listings engine. name: app-listings - description: Endpoints for creating and managing API keys. name: apikey - description: Endpoints for managing billing and subscription information. name: billing - description: Endpoints for creating and managing tables. name: tables - description: Endpoints for table columns, formula previews, and on-demand column runs. name: table-columns - description: Endpoints for table rows and manual cell edits. name: table-rows - description: Endpoints for observing and cancelling table recompute runs. name: table-runs - description: >- Endpoints for org-shared per-column display preferences: hidden, pinned, width, and colour tint. name: table-ui-prefs - description: >- Endpoints for the org-shared names given to the column tint palette: what this organisation calls each colour. Org-level, not per-table. name: table-column-color-labels - description: >- Endpoints for the enrichment action catalog, model list, presets, draft generation, and saved agents. name: table-enrichments - description: >- Endpoints for teaching a saved agent from example rows: training sessions, per-row feedback, and the proposed prompt to approve. name: agent-training - description: >- The durable audit trail of a table's enrichment actions: configured, edited, run, cancelled, and settled cost. name: table-enrichment-audit-logs - description: Endpoints for saving and applying column templates. name: table-templates - description: Server-sent change feed for a table's grid. name: table-events - description: 'Endpoints for org-shared saved table views: sort, filters, hidden columns.' name: table-views - description: >- The per-table AI Assistant: named conversations, the column suggestions a build turn produces, and the questions an analyze turn answers. name: table-assistant - description: >- Endpoints for PER-USER table preferences: favourites and recently opened. Unlike the rest of the table surface these are personal, so two members of one organisation legitimately see different answers. name: table-user-prefs - description: >- Endpoints for building a table from an uploaded CSV: upload and preview the inferred columns, commit the reviewed mapping, then poll the row load. name: table-imports - description: Endpoint for downloading a table's rows as CSV. name: table-export - description: >- Endpoints for the integration a table imports from: attach and preview it, promote imported fields into columns, and run the import on demand. name: table-sources - description: >- Endpoints for a table's recurring import cadence: set it, pause it, and read the next fire times. name: table-schedules - description: >- Endpoints for pushing a table's rows out to a connected integration: list writable destinations, derive their write capabilities, and map export columns. name: table-writeback - description: >- Endpoints backing a lookup column's setup: the connections whose records a column could read, and the identity fields one record type can be looked up by. name: table-integration-lookup - description: >- Endpoints for sourcing leads from the lead database: count and preview matches, land them in a table, and keep saved searches. name: find-leads - description: >- Endpoints for discovering a domain's subdomains from public certificate logs and landing the results in a table. name: find-subdomains - description: Endpoints for the credit balance meter and usage reporting. name: credits - description: >- Endpoints for the workspace referral program: the shareable link, the friends who joined through it, and claiming a code after signup. name: referral - description: >- Endpoints for the design partner program's customer surface: whether this workspace is a design partner, the badges its feedback has earned, and sending and reading that feedback. name: design-partner - description: >- Endpoints for the org-level AI business context — company description, ideal customer profile, buyer personas and interest signals — plus domain-based generation. name: ai-context paths: /tables/{table_id}/events/: get: tags: - table-events summary: Stream a table's change events description: >- Server-sent event stream of a table's changes: row cell deltas, run progress, and column / display-preference / row-set invalidation signals. Replaces the 2-second status poll — an idle table costs nothing. Deltas carry the row's `version`, the same watermark the rows list carries, so applying one twice or out of order is a no-op. There is deliberately NO replay log: clients refetch once on every connect, and a mid-stream gap is reported as a `resync` frame meaning the same thing. The server closes the stream after a few minutes with a `reconnect` frame; reconnect with a fresh token. Comment heartbeats keep intermediaries from dropping an idle connection. Requires Clerk authentication; API keys are rejected. There is deliberately no 404 — an unknown or foreign table streams heartbeats only, because the channel is org-scoped and leaks nothing. operationId: stream_table_events parameters: - in: path name: table_id required: true schema: format: uuid title: Table Id type: string responses: '200': content: text/event-stream: schema: $ref: '#/components/schemas/TableChangeEventSchema' type: string description: >- A stream of change events; each SSE frame's `data` is one event object. '401': content: text/event-stream: schema: $ref: '#/components/schemas/UnauthorizedResponse' description: Unauthorized '403': content: text/event-stream: schema: $ref: '#/components/schemas/ForbiddenResponse' description: Forbidden '422': content: text/event-stream: schema: $ref: '#/components/schemas/UnprocessableEntityResponse' description: Invalid request made to the API. '500': content: text/event-stream: schema: $ref: '#/components/schemas/ServerErrorResponse' description: Internal server error. '502': content: text/event-stream: schema: $ref: '#/components/schemas/ServerErrorResponse' description: Bad gateway error. '503': content: text/event-stream: schema: $ref: '#/components/schemas/ServerErrorResponse' description: Service unavailable. security: - HTTPBearer: [] components: schemas: TableChangeEventSchema: description: >- One frame of the change feed, discriminated by ``kind``. A wrapper model rather than a bare union so the whole vocabulary lands in the OpenAPI document as a single named schema the client can switch on. properties: event: description: The event body; switch on `kind`. discriminator: mapping: cell_activity: $ref: '#/components/schemas/TableCellActivityEventSchema' columns_changed: $ref: '#/components/schemas/TableColumnsChangedEventSchema' hello: $ref: '#/components/schemas/TableHelloEventSchema' reconnect: $ref: '#/components/schemas/TableReconnectEventSchema' resync: $ref: '#/components/schemas/TableResyncEventSchema' rows_changed: $ref: '#/components/schemas/TableRowsChangedEventSchema' rows_invalidated: $ref: '#/components/schemas/TableRowsInvalidatedEventSchema' run_changed: $ref: '#/components/schemas/TableRunChangedEventSchema' table_changed: $ref: '#/components/schemas/TableChangedEventSchema' table_deleted: $ref: '#/components/schemas/TableDeletedEventSchema' ui_prefs_changed: $ref: '#/components/schemas/TableUIPrefsChangedEventSchema' propertyName: kind oneOf: - $ref: '#/components/schemas/TableHelloEventSchema' - $ref: '#/components/schemas/TableRowsChangedEventSchema' - $ref: '#/components/schemas/TableRowsInvalidatedEventSchema' - $ref: '#/components/schemas/TableColumnsChangedEventSchema' - $ref: '#/components/schemas/TableUIPrefsChangedEventSchema' - $ref: '#/components/schemas/TableChangedEventSchema' - $ref: '#/components/schemas/TableDeletedEventSchema' - $ref: '#/components/schemas/TableRunChangedEventSchema' - $ref: '#/components/schemas/TableCellActivityEventSchema' - $ref: '#/components/schemas/TableResyncEventSchema' - $ref: '#/components/schemas/TableReconnectEventSchema' title: Event required: - event title: TableChangeEventSchema type: object UnauthorizedResponse: properties: detail: description: The detail of why the request is unauthorized. title: Detail type: string required: - detail title: UnauthorizedResponse type: object ForbiddenResponse: properties: detail: description: The detail of why the request is forbidden. title: Detail type: string required: - detail title: ForbiddenResponse type: object UnprocessableEntityResponse: properties: detail: description: >- The detail of the error. This is the error message to show to the user. You should also use the issues field to show more detailed error messages per field. Use this field for a single liner error message. title: Detail type: string issues: description: >- The issues that caused the error. There can be multiple issues. Each issue is a user-facing error message. items: $ref: '#/components/schemas/UnprocessableEntityIssue' title: Issues type: array required: - detail - issues title: UnprocessableEntityResponse type: object ServerErrorResponse: properties: detail: description: The detail of why the server returned an error. title: Detail type: string required: - detail title: ServerErrorResponse type: object TableCellActivityEventSchema: description: >- One live agent step for one cell of an active run. Published IMMEDIATELY, bypassing the post-commit queue — steps are telemetry about work that already happened, not table state, and a compute page's transaction spans the whole page. Never coalesced: liveness is the point. The transport is lossy by design, so clients treat the post-commit ``rows_changed`` settle as authoritative and use these frames for display only. properties: attempt: default: 1 description: >- 1-based retry attempt; an increment means the investigation restarted — clear the displayed trail. title: Attempt type: integer column_id: format: uuid title: Column Id type: string kind: const: cell_activity default: cell_activity title: Kind type: string record_id: format: uuid title: Record Id type: string run_id: anyOf: - format: uuid type: string - type: 'null' title: Run Id seq: description: >- 0-based and strictly rising across the whole cell execution, retries included — the ordering key. title: Seq type: integer step: $ref: '#/components/schemas/TableCellActivityStepSchema' table_id: format: uuid title: Table Id type: string required: - table_id - record_id - column_id - seq - step title: TableCellActivityEventSchema type: object TableColumnsChangedEventSchema: description: >- A column was created, edited, deleted, or reordered — refetch columns and rows. properties: kind: const: columns_changed default: columns_changed title: Kind type: string table_id: format: uuid title: Table Id type: string required: - table_id title: TableColumnsChangedEventSchema type: object TableHelloEventSchema: description: 'Opening frame: the stream is live and the client should resync once.' properties: heartbeat_seconds: description: >- Idle heartbeat cadence; treat silence beyond a small multiple as death. title: Heartbeat Seconds type: integer kind: const: hello default: hello title: Kind type: string table_id: format: uuid title: Table Id type: string required: - table_id - heartbeat_seconds title: TableHelloEventSchema type: object TableReconnectEventSchema: description: >- Final frame: the stream reached its maximum age. Reconnect for a fresh one. properties: kind: const: reconnect default: reconnect title: Kind type: string table_id: format: uuid title: Table Id type: string required: - table_id title: TableReconnectEventSchema type: object TableResyncEventSchema: description: |- Events were lost; refetch everything. Emitted when this client could not keep up with its queue, or when the server's Valkey link dropped and reconnected. There is no replay log by design — a refetch is cheaper than maintaining one. properties: kind: const: resync default: resync title: Kind type: string reason: title: Reason type: string table_id: format: uuid title: Table Id type: string required: - table_id - reason title: TableResyncEventSchema type: object TableRowsChangedEventSchema: description: One or more rows changed; apply the deltas directly, no refetch needed. properties: kind: const: rows_changed default: rows_changed title: Kind type: string rows: items: $ref: '#/components/schemas/TableRowDeltaSchema' title: Rows type: array table_id: format: uuid title: Table Id type: string required: - table_id - rows title: TableRowsChangedEventSchema type: object TableRowsInvalidatedEventSchema: description: |- The row SET changed (rows created or deleted) — refetch the page. Membership and ordering changed, and a keyset window cannot be patched locally, so this is deliberately an invalidation rather than a delta. properties: kind: const: rows_invalidated default: rows_invalidated title: Kind type: string record_ids: anyOf: - items: format: uuid type: string type: array - type: 'null' description: >- The affected rows when known; null for a whole-table drain or a degraded batch. title: Record Ids row_count: description: The table's authoritative row count after the change. title: Row Count type: integer table_id: format: uuid title: Table Id type: string required: - table_id - row_count title: TableRowsInvalidatedEventSchema type: object TableRunChangedEventSchema: description: A recompute run was created, progressed, or reached a terminal status. properties: kind: const: run_changed default: run_changed title: Kind type: string run: $ref: '#/components/schemas/TableRunDeltaSchema' table_id: format: uuid title: Table Id type: string required: - table_id - run title: TableRunChangedEventSchema type: object TableChangedEventSchema: description: The table definition changed (name, description, or row counter). properties: description: anyOf: - type: string - type: 'null' title: Description kind: const: table_changed default: table_changed title: Kind type: string name: title: Name type: string row_count: title: Row Count type: integer table_id: format: uuid title: Table Id type: string updated_at: format: date-time title: Updated At type: string required: - table_id - name - description - row_count - updated_at title: TableChangedEventSchema type: object TableDeletedEventSchema: description: The table was deleted; the next read will 404. properties: kind: const: table_deleted default: table_deleted title: Kind type: string table_id: format: uuid title: Table Id type: string required: - table_id title: TableDeletedEventSchema type: object TableUIPrefsChangedEventSchema: description: >- Display preferences changed — refetch the column list ALONE. Separate from ``columns_changed`` for the same reason the status watermarks are separate: a hide, pin, resize, or recolour must never refetch the rows page and stats that a definition change refetches. properties: kind: const: ui_prefs_changed default: ui_prefs_changed title: Kind type: string table_id: format: uuid title: Table Id type: string required: - table_id title: TableUIPrefsChangedEventSchema type: object UnprocessableEntityIssue: properties: input: anyOf: - type: string - type: integer - type: number - type: boolean - items: {} type: array - additionalProperties: true type: object description: The user's input that caused the error. title: Input loc: description: >- The location of the error. Always contains 1 or 2 elements. The first element is the type of location (e.g. 'body', 'query', 'path', 'header'). The second element is the name of the field that caused the error. If the error is not related to a specific field, the second element is not present. items: type: string title: Loc type: array msg: description: The message of the error. The error message to show to the user. title: Msg type: string type: description: >- The type of the error. Useful for frontend code to handle different types of errors. title: Type type: string required: - loc - msg - type - input title: UnprocessableEntityIssue type: object TableCellActivityStepSchema: description: >- One agent research step, JSON-native. Plain strings rather than the agent domain's enums: this package sits below ``table_agent`` and cannot import it, exactly like ``TableRunRowScopeSchema.kind``. ``action`` values today are ``search`` | ``map`` | ``scrape`` | ``crawl`` | ``mcp_tool`` | ``finish``; ``outcome`` values are ``completed`` | ``failed`` | ``refused``. Clients must tolerate new tokens. properties: action: title: Action type: string detail: description: The search query, target URL, or tool call — the step's input. title: Detail type: string duration_ms: anyOf: - type: integer - type: 'null' title: Duration Ms observation: description: One line on what came back. title: Observation type: string outcome: default: completed title: Outcome type: string thought: anyOf: - type: string - type: 'null' description: The model's stated reasoning for choosing this step. title: Thought required: - action - detail - observation title: TableCellActivityStepSchema type: object TableRowDeltaSchema: description: >- One row's change, as a PARTIAL patch over its cells. ``cells`` carries only the columns this write touched, so a compute page's frame is proportional to the columns computed rather than to the table's width. Clients merge, never replace. There is no row-level version and no cleared list. Each cell carries its own monotonic watermark, so a delta applies per cell and applying one twice or out of order is a no-op; and a cleared cell is PRESENT with a null value rather than absent, so a partial map expresses a clear on its own. properties: cells: additionalProperties: $ref: '#/components/schemas/TableCellDeltaSchema' description: Only the columns this write touched, keyed by str(column_id). title: Cells type: object record_id: format: uuid title: Record Id type: string required: - record_id - cells title: TableRowDeltaSchema type: object TableRunDeltaSchema: description: >- One run's current state; mirrors the REST run schema so clients can drop it straight in. properties: cells_done: title: Cells Done type: integer cells_failed: title: Cells Failed type: integer cells_no_data: default: 0 description: No-data cells — ran clean but found nothing. title: Cells No Data type: integer cells_skipped: default: 0 description: Deliberately skipped cells — missing input or false condition. title: Cells Skipped type: integer cells_total: title: Cells Total type: integer column_id: anyOf: - format: uuid type: string - type: 'null' title: Column Id completed_at: anyOf: - format: date-time type: string - type: 'null' title: Completed At created_at: format: date-time title: Created At type: string error: anyOf: - type: string - type: 'null' title: Error id: format: uuid title: Id type: string row_scope: anyOf: - $ref: '#/components/schemas/TableRunRowScopeSchema' - type: 'null' description: >- The rows this run resolved to. Optional so a frame enqueued by an older worker still deserializes mid-rolling-deploy; absent reads as all_rows. started_at: anyOf: - format: date-time type: string - type: 'null' title: Started At status: title: Status type: string table_id: format: uuid title: Table Id type: string trigger: title: Trigger type: string required: - id - table_id - trigger - status - cells_total - cells_done - cells_failed - error - created_at - started_at - completed_at title: TableRunDeltaSchema type: object TableCellDeltaSchema: description: >- One cell's post-write state. Deliberately carries NO ``computing`` flag. That flag is derived (``stale`` AND the table has an active run) and a write has no idea whether a run is active, so carrying it here would flicker cells out of their computing state mid-run. Clients derive it from their own active-run state, exactly as the REST responses do. properties: computed_at: anyOf: - format: date-time type: string - type: 'null' description: Last compute time, for formula cells. title: Computed At confidence: anyOf: - type: string - type: 'null' description: The agent's own read on its answer, when the action reports one. title: Confidence credits_charged: anyOf: - type: integer - type: 'null' description: Credits the last successful enrichment charged for this cell. title: Credits Charged error: anyOf: - type: string - type: 'null' description: Evaluation error, when the cell is in an error state. title: Error error_class: anyOf: - type: string - type: 'null' description: The failure's taxonomy class, when the cell is errored. title: Error Class manual_override: default: false description: A hand-entered correction runs will not overwrite. title: Manual Override type: boolean settled_as: default: pending description: >- How the last attempt on this cell ENDED, never what it shows. The grid needs it to tell `no_data` (ran, found nothing) from `pending` (never ran) — both render blank and neither carries an error. enum: - succeeded - no_data - skipped - failed - pending title: Settled As type: string skipped_reason: anyOf: - type: string - type: 'null' description: Why an enrichment run skipped this cell, when it did. title: Skipped Reason stale: default: false description: Whether the value is out of date and awaits a recompute. title: Stale type: boolean updated_at: description: When this cell was last written. format: date-time title: Updated At type: string value: description: The cell's value; null renders the column default. title: Value version: description: Per-cell watermark; apply only if at least the cached one. title: Version type: integer required: - value - error - version - updated_at title: TableCellDeltaSchema type: object TableRunRowScopeSchema: description: >- The rows a run resolved to, so a reader can mark exactly those cells busy. ``kind`` is a plain string rather than the run domain's enum: this package sits under the table stratum and cannot import from it, which is also why ``trigger`` and ``status`` above are strings. Its values are ``all_rows`` | ``record_ids`` | ``unlisted``; the first and last both mean "assume every row". properties: kind: title: Kind type: string record_ids: anyOf: - items: format: uuid type: string type: array - type: 'null' description: >- The exact rows the run will touch; populated for the record_ids kind only. title: Record Ids rows: anyOf: - type: integer - type: 'null' description: Rows the resolved scope covers; None for all rows. title: Rows required: - kind title: TableRunRowScopeSchema type: object securitySchemes: HTTPBearer: scheme: bearer type: http ````