---
title: "List and filter entities"
method: GET
path: "/api/v1/ackdb/entities"
tags: ["ackDB"]
---

# List and filter entities

`GET /api/v1/ackdb/entities`

## Request

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

Returns a paginated list of entities. Supports text search across entity names and multi-trait filtering via `traitFilter` query params.

**Trait filters:** Each `traitFilter` param uses `traitKey:operator:value` format. Multiple filters are combined with AND logic.

**Operators:** `eq`, `neq` (string/text comparison), `gt`, `gte`, `lt`, `lte` (numeric), `is_null`, `is_not_null` (existence check - no value needed).

**Examples:**
- `?traitFilter=stripe_plan:eq:enterprise` - entities on enterprise plan
- `?traitFilter=stripe_total_paid_cents:gte:10000` - entities that paid >= $100
- `?traitFilter=stripe_plan:eq:enterprise&traitFilter=stripe_status:eq:active` - enterprise + active
- `?traitFilter=stripe_plan:is_null` - entities without a Stripe plan

**Hidden companies (#493, #505):** a company whose only ingested evidence comes from a source flagged `contextOnly` (`job` → a past employer, `education` → a school) is context on somebody's record, not an account. A company minted solely as a relationship endpoint is also hidden until real evidence arrives. Both are EXCLUDED from this browse list; pass `includeReference=true` to include them. They remain reachable by id, by domain, and via `GET /entities/search`.

**Internal companies (#567):** a company holding a `domain` link listed in `internal_domains` is the deployment ITSELF, never an account. Same treatment: excluded here, revealed by `includeReference=true`, always reachable by id/domain/search. Unlike a reference company it is never promoted by activity — data landing on your own domain is still your own domain.

## Query parameters

- `search` string
- `traitFilter` string[]
- `limit` integer
- `offset` integer
- `includeReference` boolean

## Response `200`

Paginated list of entities

- object
  - `data` AckdbEntity[], required
    - `entityId` string, required: Internal ULID identifier for the entity.
    - `name` string, required: Human-readable entity name (e.g. company name). May be null for auto-created entities.
    - `createdAt` string, date-time, required: When the entity was first created.
    - `updatedAt` string, date-time, required: When the entity was last updated.
  - `pagination` AckdbPaginationMeta, required: 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).

---

[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)