Segments

A segment is a saved set of conditions, such as "iOS users who bought pro_yearly in the last 90 days". Use it as the audience of a server push, an in-app message or a journey. The concepts are in the Segments guide.

These endpoints live on the SDK host: https://sdk.sqd.link on grovs Cloud, https://sdk.<SERVER_HOST> when you self-host. Send your project key in the PROJECT-KEY header. Send production or test in the ENVIRONMENT header. Each environment has its own segments.

Availability: an active paid plan on grovs Cloud. Always on for self-hosted Enterprise. Without it, every call answers 403 with error_code: "enterprise_required". Estimates, counts and identifier lists need ClickHouse.

Rate limit: 120 requests a minute per project key, shared with in-app messages. Over it, the answer is 429 with error_code: "rate_limited" and a Retry-After header.

Dashboard only: the member list, breakdowns, CSV exports, size history and the identifier list preview and download.

IDs: segment IDs are hashids, such as gk3x.

The segment object

Attributes

idstring

Hashid of the segment.

namestring

Up to 255 characters.

descriptionstring | null

Free text.

definitionobject

The conditions, in canonical form: keys sorted and defaults filled in. See The definition.

definition_hashstring

Digest of the canonical definition. It changes when the definition does.

archivedboolean

Archived segments are not evaluated and cannot be targeted.

has_identifier_listboolean

true once an identifier list was uploaded.

identifier_listobject | null

count and updated_at of the uploaded list. null without one.

sizeobject | null

The latest daily size snapshot for the current definition: date, persons, devices. null when there is none from the last 7 days, such as for a new or just edited segment.

created_atstring

ISO 8601.

updated_atstring

ISO 8601.

JSON

The segment object

JSON

{
  "id": "gk3x",
  "name": "iOS pro buyers",
  "description": "Bought pro_yearly in the last 90 days",
  "definition": {
    "version": 1,
    "operator": "and",
    "groups": [
      {
        "operator": "and",
        "conditions": [
          { "type": "device", "field": "platform", "op": "is", "value": ["ios"], "mode": "current" },
          { "type": "purchase", "product_id": ["pro_yearly"], "count": 1, "window": { "last_days": 90 } }
        ]
      }
    ]
  },
  "definition_hash": "a1b2c3d4…",
  "archived": false,
  "has_identifier_list": false,
  "identifier_list": null,
  "size": { "date": "2026-10-21", "persons": 4821, "devices": 5310 },
  "created_at": "2026-10-01T10:00:00.000Z",
  "updated_at": "2026-10-21T04:00:12.000Z"
}

The definition

A definition has two levels. Conditions sit inside groups, and each group's operator (and or or) combines its conditions. The top-level operator combines the groups. Groups cannot be nested.

Definition

versionintegerRequired

Always 1.

operatorenumRequired

and or or. Combines the groups.

groupsarrayRequired

1 to 5 groups. Each has an operator and 1 to 10 conditions.

Each condition has a type and fields that depend on it. Every field, operator and example is in Condition types.

`type`	Matches	Key fields
`event`	A built-in event, a custom event, or any activity	One of `event_type`, `event_name`, `any: true`. `count`, `window`, `filters`, `negate`
`device`	Device and app fields	`field`, `op`, `value`, `mode` (`current` or `used` with a `window`)
`profile`	A property your app set on the user	`field` (`properties.<key>`), `op`, `value`
`first_seen`	When the person first appeared	`op` (`gte` or `lte`), `value` (a date)
`identifier`	Your own user ID, or the uploaded list	`op` (`is`, `contains`, `is_set`, `is_not_set`, `in_list`, `not_in_list`), `value`
`acquisition`	The install or reinstall that brought the person in	`field` (`link_id`, `campaign_id`, `tracking_source`, `tracking_medium`), `op`, `value`, `window`
`purchase`	In-app purchases and subscriptions	`product_id`, `purchase_type`, `store_source`, `count`, `min_total_usd_cents`, `window`, `negate`

A window is { "last_days": N } or { "from": "YYYY-MM-DD", "to": "YYYY-MM-DD" }, in UTC and whole days.

A "did not" condition (negate, is_not, is_not_set, not_in_list) must sit in an and group with a positive one.

Limit	Value
Groups per definition	5
Conditions per group	10
Filters per `event` condition	25
Values per condition or filter	100
Value length	256 bytes
Identifiers per uploaded list	200,000
`event` and `device` windows	90 days
`acquisition` and `purchase` windows	365 days

purchase conditions need revenue tracking. Read the limits your install runs with from the condition catalogue.

JSON

A definition

JSON

{
  "version": 1,
  "operator": "or",
  "groups": [
    {
      "operator": "and",
      "conditions": [
        { "type": "event", "event_type": "app_open", "window": { "last_days": 30 } },
        { "type": "event", "event_name": "checkout", "negate": true, "window": { "last_days": 30 } }
      ]
    },
    {
      "operator": "and",
      "conditions": [
        { "type": "identifier", "op": "in_list" }
      ]
    }
  ]
}

List segments

GET/api/v1/sdk/server/segments

Returns up to 200 segments of the environment, most recently updated first.

AuthProject keyAuthentication ›

Headers

PROJECT-KEYstringRequired

Your project key.

ENVIRONMENTstringRequired

production or test.

Query

archivedboolean

true lists archived segments instead of active ones. Default false.

Returns 200 with segments, a list of segment objects, and truncated: true when there are more than 200.

Errors

400Missing PROJECT-KEY, or ENVIRONMENT is not production or test.

403Invalid credentials, or enterprise_required.

429rate_limited: over 120 requests a minute for this key.

Request · cURL

curl -X GET "https://sdk.sqd.link/api/v1/sdk/server/segments" \
  -H "PROJECT-KEY: $GROVS_PROJECT_KEY" \
  -H "ENVIRONMENT: production"

JSON

{
  "segments": [
    {
      "id": "gk3x",
      "name": "iOS pro buyers",
      "description": null,
      "definition": { "version": 1, "operator": "and", "groups": ["…"] },
      "definition_hash": "a1b2c3d4…",
      "archived": false,
      "has_identifier_list": false,
      "identifier_list": null,
      "size": { "date": "2026-10-21", "persons": 4821, "devices": 5310 },
      "created_at": "2026-10-01T10:00:00.000Z",
      "updated_at": "2026-10-21T04:00:12.000Z"
    }
  ],
  "truncated": false
}

Get the condition catalogue

GET/api/v1/sdk/server/segments/fields

Returns every condition type with its fields, operators and window caps, plus the limits this install runs with. Use it to build or validate definitions.

AuthProject keyAuthentication ›

Headers

PROJECT-KEYstringRequired

Your project key.

ENVIRONMENTstringRequired

production or test.

Returns 200 with version, limits and conditions. profile lists up to 200 property_keys seen on your users. purchase has enabled: false while revenue tracking is off.

Errors

400Missing PROJECT-KEY, or ENVIRONMENT is not production or test.

403Invalid credentials, or enterprise_required.

Request · cURL

curl -X GET "https://sdk.sqd.link/api/v1/sdk/server/segments/fields" \
  -H "PROJECT-KEY: $GROVS_PROJECT_KEY" \
  -H "ENVIRONMENT: production"

JSON

{
  "version": 1,
  "limits": {
    "groups": 5,
    "conditions_per_group": 10,
    "filters": 25,
    "values": 100,
    "value_bytes": 256,
    "identifier_list": 200000
  },
  "conditions": [
    {
      "type": "event",
      "event_types": ["app_open", "view", "open", "install", "…"],
      "filter_columns": ["screen_name", "platform", "app_version", "…"],
      "filter_ops": ["is", "is_not", "contains"],
      "property_prefix": "properties.",
      "max_window_days": 90,
      "negatable": true
    },
    { "type": "profile", "ops": ["is", "is_not", "contains", "is_set", "is_not_set"], "property_prefix": "properties.", "property_keys": ["plan", "clinic_id"] },
    { "type": "purchase", "enabled": true, "purchase_types": ["subscription", "one_time"], "max_window_days": 365, "negatable": true },
    "…"
  ]
}

Estimate a segment

POST/api/v1/sdk/server/segments/estimate

Counts the people and devices a definition matches without saving it. Send a draft definition, a saved segment_id, or both to estimate an edit of that segment against its uploaded identifier list.

AuthProject keyAuthentication ›

Headers

PROJECT-KEYstringRequired

Your project key.

ENVIRONMENTstringRequired

production or test.

Body

definitionobject

A definition. Required without segment_id.

segment_idstring

An active segment. Alone, it estimates that segment. With definition, its identifier list backs the draft's in_list and not_in_list.

Returns 200 with persons, devices, approximate (always false: counts are exact) and incomplete. incomplete is true when a window reaches past your data retention, so the count may be low.

Errors

404Segment not found: unknown or archived segment_id.

422The definition is invalid, or window_expired, or query_too_heavy.

429segment_busy: too many segment queries are running, retry in a few seconds. Or rate_limited.

503clickhouse_unavailable.

Request · cURL

curl -X POST "https://sdk.sqd.link/api/v1/sdk/server/segments/estimate" \
  -H "PROJECT-KEY: $GROVS_PROJECT_KEY" \
  -H "ENVIRONMENT: production" \
  -H "Content-Type: application/json" \
  -d '{
  "definition": {
    "version": 1,
    "operator": "or",
    "groups": [
      {
        "operator": "and",
        "conditions": [
          {
            "type": "event",
            "event_name": "checkout",
            "window": { "last_days": 30 }
          }
        ]
      }
    ]
  }
}'

JSON

{
  "persons": 1204,
  "devices": 1388,
  "approximate": false,
  "incomplete": false
}

Create a segment

POST/api/v1/sdk/server/segments

Saves a segment. The definition is validated and stored in canonical form.

AuthProject keyAuthentication ›

Headers

PROJECT-KEYstringRequired

Your project key.

ENVIRONMENTstringRequired

production or test.

Body

namestringRequired

Up to 255 characters.

definitionobjectRequired

A definition. A fixed window that starts before your data retention cutoff is refused.

descriptionstring

Free text.

Returns 201 with segment, a segment object.

Errors

400Missing PROJECT-KEY, or ENVIRONMENT is not production or test.

403Invalid credentials, or enterprise_required.

422definition must be an object, or the name or definition is invalid. error names the condition path.

429rate_limited.

Request · cURL

curl -X POST "https://sdk.sqd.link/api/v1/sdk/server/segments" \
  -H "PROJECT-KEY: $GROVS_PROJECT_KEY" \
  -H "ENVIRONMENT: production" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "iOS pro buyers",
  "description": "Bought pro_yearly in the last 90 days",
  "definition": {
    "version": 1,
    "operator": "and",
    "groups": [
      {
        "operator": "and",
        "conditions": [
          {
            "type": "device",
            "field": "platform",
            "op": "is",
            "value": ["ios"],
            "mode": "current"
          },
          {
            "type": "purchase",
            "product_id": ["pro_yearly"],
            "window": { "last_days": 90 }
          }
        ]
      }
    ]
  }
}'

JSON

{
  "segment": {
    "id": "gk3x",
    "name": "iOS pro buyers",
    "description": "Bought pro_yearly in the last 90 days",
    "definition": { "version": 1, "operator": "and", "groups": ["…"] },
    "definition_hash": "a1b2c3d4…",
    "archived": false,
    "has_identifier_list": false,
    "identifier_list": null,
    "size": null,
    "created_at": "2026-10-22T09:00:00.000Z",
    "updated_at": "2026-10-22T09:00:00.000Z"
  }
}

Retrieve a segment

GET/api/v1/sdk/server/segments/{segment_id}

Returns one segment, archived or not.

AuthProject keyAuthentication ›

Headers

PROJECT-KEYstringRequired

Your project key.

ENVIRONMENTstringRequired

production or test.

Path

segment_idstringRequired

The segment's id.

Returns 200 with segment, a segment object.

Errors

403Invalid credentials, or enterprise_required.

404Segment not found, or it belongs to the other environment.

Request · cURL

curl -X GET "https://sdk.sqd.link/api/v1/sdk/server/segments/{segment_id}" \
  -H "PROJECT-KEY: $GROVS_PROJECT_KEY" \
  -H "ENVIRONMENT: production"

JSON

{
  "segment": {
    "id": "gk3x",
    "name": "iOS pro buyers",
    "archived": false,
    "size": { "date": "2026-10-21", "persons": 4821, "devices": 5310 },
    "…": "…"
  }
}

Update a segment

PATCH/api/v1/sdk/server/segments/{segment_id}

Changes only the fields you send. A new definition gets a new definition_hash and starts a fresh size history. Campaigns already launched on the segment keep the audience they froze at launch.

AuthProject keyAuthentication ›

Headers

PROJECT-KEYstringRequired

Your project key.

ENVIRONMENTstringRequired

production or test.

Path

segment_idstringRequired

The segment's id.

Body

namestring

Up to 255 characters.

descriptionstring | null

Free text.

definitionobject

A full definition. It replaces the old one.

archivedboolean

false restores an archived segment.

Returns 200 with segment, a segment object.

Errors

404Segment not found.

422definition must be an object, or the name or definition is invalid.

429rate_limited.

Request · cURL

curl -X PATCH "https://sdk.sqd.link/api/v1/sdk/server/segments/{segment_id}" \
  -H "PROJECT-KEY: $GROVS_PROJECT_KEY" \
  -H "ENVIRONMENT: production" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "iOS pro buyers, 30 days",
  "definition": {
    "version": 1,
    "operator": "and",
    "groups": [
      {
        "operator": "and",
        "conditions": [
          {
            "type": "device",
            "field": "platform",
            "op": "is",
            "value": ["ios"],
            "mode": "current"
          },
          {
            "type": "purchase",
            "product_id": ["pro_yearly"],
            "window": { "last_days": 30 }
          }
        ]
      }
    ]
  }
}'

JSON

{
  "segment": {
    "id": "gk3x",
    "name": "iOS pro buyers, 30 days",
    "definition_hash": "f7e6d5c4…",
    "size": null,
    "…": "…"
  }
}

Archive a segment

DELETE/api/v1/sdk/server/segments/{segment_id}

Archives the segment. It is not deleted: it stops being evaluated, drops out of the list and cannot be targeted. Restore it with Update a segment and archived: false.

AuthProject keyAuthentication ›

Headers

PROJECT-KEYstringRequired

Your project key.

ENVIRONMENTstringRequired

production or test.

Path

segment_idstringRequired

The segment's id.

Returns 200 with a message.

Errors

404Segment not found.

429rate_limited.

Request · cURL

curl -X DELETE "https://sdk.sqd.link/api/v1/sdk/server/segments/{segment_id}" \
  -H "PROJECT-KEY: $GROVS_PROJECT_KEY" \
  -H "ENVIRONMENT: production"

JSON

{
  "message": "Segment archived"
}

Count a segment

POST/api/v1/sdk/server/segments/{segment_id}/count

Returns the exact number of people and devices in a saved segment. The first count after a change can take a few seconds. The result is reused for a few minutes, so repeat calls are fast.

Server counts run in their own pool, apart from the dashboard's.

AuthProject keyAuthentication ›

Headers

PROJECT-KEYstringRequired

Your project key.

ENVIRONMENTstringRequired

production or test.

Path

segment_idstringRequired

An active segment's id.

Returns 200 with persons, devices, incomplete and result_id, the ID of the computed result.

Errors

404Segment not found, or it is archived.

422invalid_definition, window_expired or query_too_heavy.

429segment_busy: retry in a few seconds. Or rate_limited.

503clickhouse_unavailable.

Request · cURL

curl -X POST "https://sdk.sqd.link/api/v1/sdk/server/segments/{segment_id}/count" \
  -H "PROJECT-KEY: $GROVS_PROJECT_KEY" \
  -H "ENVIRONMENT: production"

JSON

{
  "persons": 4821,
  "devices": 5310,
  "incomplete": false,
  "result_id": "3f9a1c2e…"
}

Replace the identifier list

POST/api/v1/sdk/server/segments/{segment_id}/identifier_list

Stores a list of your user IDs on the segment, replacing any earlier list. Match it with an identifier condition and op: "in_list" or "not_in_list". Use it when your server knows who belongs, such as members of a loyalty tier.

Identifiers are stored exactly as sent and compared to the user ID your app sets through the SDK. A failed upload keeps the previous list.

AuthProject keyAuthentication ›

Headers

PROJECT-KEYstringRequired

Your project key.

ENVIRONMENTstringRequired

production or test.

Path

segment_idstringRequired

An active segment's id.

Body

identifiersstring[]Required

1 to 200,000 strings of 1 to 256 bytes. Duplicates count once.

Returns 200 with the updated segment and count, the number of distinct identifiers stored.

Errors

404Segment not found, or it is archived.

409upload_in_progress: another upload for this segment is still running.

422The list is empty, over 200,000 entries, or has an identifier that is not a string of 1-256 bytes.

503clickhouse_unavailable.

Request · cURL

curl -X POST "https://sdk.sqd.link/api/v1/sdk/server/segments/{segment_id}/identifier_list" \
  -H "PROJECT-KEY: $GROVS_PROJECT_KEY" \
  -H "ENVIRONMENT: production" \
  -H "Content-Type: application/json" \
  -d '{
  "identifiers": ["member-4471", "member-9021", "member-4471"]
}'

JSON

{
  "segment": {
    "id": "gk3x",
    "has_identifier_list": true,
    "identifier_list": { "count": 2, "updated_at": "2026-10-22T09:14:03.120Z" },
    "…": "…"
  },
  "count": 2
}

Was this page helpful?

Last updated 2026-10-26