---
title: "Cross-entity event search"
method: GET
path: "/api/v1/ackdb/entities/events"
tags: ["ackDB"]
---

# Cross-entity event search

`GET /api/v1/ackdb/entities/events`

## Request

- Base URL: `http://localhost:3009`
- URL: `http://localhost:3009/api/v1/ackdb/entities/events`
- Auth: HTTP bearer

Search events across all entities. Filterable by source, event type, and date range. Returns events with entity names. Use for cross-entity queries like 'all Stripe refunds in February' without per-entity N+1 calls.

## Query parameters

- `source` string
- `eventType` string
- `since` string, date-time
- `until` string, date-time
- `limit` integer
- `offset` integer
- `cursor` string
- `graphRoot` string
- `graphScope` 'parents' | 'children' | 'connected'
- `graphMaxDepth` integer
- `graphAsOf` string, date-time
- `graphRelationshipType` string[]
- `personId` string
- `ownership` 'person' | 'company'

## Response `200`

Paginated list of events across entities. Default mode: `pagination: { total, limit, offset }`. Crawl mode (`cursor` given): `pagination: { limit, nextCursor, total? }`.

- object
  - `data` AckdbEntityEvent[], required
    - `id` string, required: ULID identifier for the event.
    - `entityId` unknown, required
    - `source` string, required: Source system that produced this event.
    - `eventType` string, required: Type of event (e.g. message, payment, subscription_change).
    - `summary` string, required: Human-readable summary of the event.
    - `metadata` object, required: Source-specific event metadata.
    - `timestamp` string, date-time, required: When this event occurred in the source system.
    - `createdAt` string, date-time, required: When this event record was created in ackDB.
    - `contactId` unknown, required
    - `personId` unknown, required
  - `pagination` union, required
    - AckdbPaginationMeta: Pagination metadata included in paginated responses.
      - `total` integer, required: Total number of records matching the query.
      - `limit` integer, required: Maximum number of records returned in this response.
      - `offset` integer, required: Number of records skipped.
      - `totalIsLowerBound` boolean: When true, `total` is a lower bound rather than an exact count. The Observe company query returns this when the count query was rejected or timed out and the result count was clamped (e.g. total=1000, totalIsLowerBound=true).
    - object: Crawl-mode pagination (`cursor` given).
      - `limit` integer, required
      - `nextCursor` string, nullable, required: Pass back as `cursor` for the next page; null when the crawl is complete.
      - `total` integer: Exact filtered total — first page (empty `cursor`) only.

---

[API](https://skmtc.dev/floqer/apis/floqer-public-api.md) - [All operations](https://skmtc.dev/floqer/apis/floqer-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/floqer/apis/floqer-public-api/revisions/fce50dc07b20?raw)