---
title: "Get a segment"
method: GET
path: "/api/v1/ackdb/observe/segments/{id}"
tags: ["ackDB"]
---

# Get a segment

`GET /api/v1/ackdb/observe/segments/{id}`

## Request

- Base URL: `http://localhost:3009`
- URL: `http://localhost:3009/api/v1/ackdb/observe/segments/{id}`
- Auth: HTTP bearer

Returns a single saved Segment by id, including the caller's effective `access` (#284). 403 if the caller cannot see it.

## Path parameters

- `id` string, required

## Response `200`

The segment.

- object
  - `data` AckdbSegment, required: A saved Observe Segment - config only (no data snapshot). Owned + per-user shared (#284); soft-deleted via deleted_at.
    - `id` string, required: ULID.
    - `name` string, required
    - `description` string
    - `entityKind` 'company' | 'contact' | 'person', required: Home (authoring) grain - the vocabulary the filter/sort/columns are written in. Every segment is also projectable to the other grains at read time via GET /observe/segments/{id}/results?grain=…, so this is where the filter was authored, not the only grain it can render.
    - `filter` AckdbObserveFilterGroup, required: A boolean group combining child nodes with AND/OR.
      - `type` 'group', required
      - `op` 'and' | 'or', required: How children are combined.
      - `children` AckdbObserveFilter[], required
        - union: Recursive Observe filter DSL. A node is either a boolean `group` (with `op` and a `children` array of further nodes) or a leaf condition (`trait`, `attribute`, `event`, or `event_field`). The root node is always a group. Empty groups compile to TRUE (match all).
          - object: A boolean group combining child nodes with AND/OR.
            - `type` 'group', required
            - `op` 'and' | 'or', required: How children are combined.
            - `children` AckdbObserveFilter[], required
          - object: A condition on a registered entity trait. `traitKey` is whitelisted against the field catalog; the operator must be legal for the trait's valueType.
            - `type` 'trait', required
            - `traitKey` string, required
            - `operator` 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'contains' | 'not_contains' | 'in' | 'is_null' | 'is_not_null' | 'in_last_days' | 'more_than_days_ago' | 'in_next_days', required
            - `value` union: Scalar or array depending on the operator. Omitted for is_null/is_not_null. For in_last_days, more_than_days_ago and in_next_days, a positive integer day count on a date field, at most 36500 days.
              - …
          - object: A condition on a fixed entity attribute (name, domain, status, timestamps, event counts, sources, last activity, or source presence).
            - `type` 'attribute', required
            - `field` 'name' | 'created_at' | 'updated_at' | 'domain' | 'status' | 'event_count' | 'last_active' | 'sources' | 'source_present', required
            - `operator` 'eq' | 'neq' | 'contains' | 'not_contains' | 'in' | 'gt' | 'gte' | 'lt' | 'lte' | 'within_days' | 'is_null' | 'is_not_null' | 'in_last_days' | 'more_than_days_ago' | 'in_next_days', required
            - `value` union: Scalar or array depending on the operator. Omitted for is_null/is_not_null. For in_last_days, more_than_days_ago and in_next_days, a positive integer day count on a date field, at most 36500 days.
              - …
          - object: A condition on the entity's event timeline. `eventType` is source-prefixed and whitelisted against the catalog. `withinDays` bounds the lookback; `count` is used by count_gte/count_lte.
            - `type` 'event', required
            - `eventType` string, required
            - `source` string
            - `predicate` 'exists' | 'not_exists' | 'count_gte' | 'count_lte', required
            - `count` integer
            - `withinDays` integer
          - object: A condition on a promoted event-metadata field's reduced scalar value (#212). `columnKey` is the synthetic field-catalog key (`emf__<source>__<field>` for the latest value, or `…__sum` for a numeric running total) and is whitelisted against the catalog; the operator must be legal for the field's valueType (same legality as a trait of that type).
            - `type` 'event_field', required
            - `columnKey` string, required
            - `operator` 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'contains' | 'not_contains' | 'in' | 'is_null' | 'is_not_null' | 'in_last_days' | 'more_than_days_ago' | 'in_next_days', required
            - `value` union: Scalar or array depending on the operator. Omitted for is_null/is_not_null. For in_last_days, more_than_days_ago and in_next_days, a positive integer day count on a date field, at most 36500 days.
              - …
    - `sort` AckdbSegmentSort[], required
      - `field` string, required
      - `dir` 'asc' | 'desc', required
    - `columns` AckdbSegmentColumn[], required
      - `field` string, required
      - `frozen` boolean
      - `width` number: Persisted column width in px (per-segment; presentation only).
    - `isDefault` boolean, required: True when this Segment is the default view for its entity_kind (one per kind).
    - `baseSegmentId` unknown, required
    - `ownerEmail` string, required: The segment's OWNER (#284) - the creator's JWT email. null = legacy / service-created = grandfathered org-visible + editable. Stamped server-side on create (never accepted from the client) and immutable thereafter; sharing with teammates is per-member via /shares.
    - `access` 'owner' | 'edit' | 'view': The CALLER's effective role on this segment (#284). Present on single reads; drives client action gating (owner/edit may save; owner only may delete / manage shares / set default).
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required

## Other responses

- `403`: Caller cannot see the segment (#284).
- `404`: Segment not found.

---

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