GetSegments - ThriveStack API Reference

How to use this API: Call GetSegments to discover the id or systemName of a saved segment, then pass that value as segmentId in a GetAccounts or GetUsers request to filter results by that segment's saved criteria. For end-to-end examples, see the Account Intelligence playbooks.

API details

Property	Value
Endpoint	`POST /growth-intelligence`
Protocol	GraphQL over HTTP
Authentication	`x-api-key` header
Content-Type	`application/json`
Operation	`query GetSegments`
Response format	JSON

What you send

Operation query GetSegments($input: GetSegmentsRequest!). The single field is optional — send an empty input to list every segment.

Field	Type	Required	Description
`entityType`	`String`	No	Limit results to one type: `"Accounts"` or `"Users"`. Omit to return segments of all types.

What you get

A GetSegmentsResponse — the segments available for your product / environment:

{
  "data": {
    "getSegments": {
      "segments": [ Segment, … ]   // all segments, or only the requested entityType
    }
  }
}

Each Segment describes one saved list. Use its id or systemName as the segmentId on GetAccounts / GetUsers.

Segment fields

Every field returned on each Segment.

Path	Type	Description	Example
`id`	`String!`	Unique segment identifier (UUID)	`"a52e828c-c980-421e-88cb-91878d945de8"`
`name`	`String!`	Display name	`"Enterprise Accounts"`
`systemName`	`String!`	Stable slug — the recommended value to pass as `segmentId`	`"enterprise_accounts"`
`description`	`String!`	Human description of the segment (may be empty)	`"Accounts with 250+ employees."`
`isSystem`	`Boolean!`	Whether this is a built-in (system) segment	`true`
`type`	`String!`	`filtered` (driven by saved filters) or `curated` (a manually-maintained list)	`"filtered"`
`entityType`	`String!`	What the segment lists: `Accounts`, `Users`, or `Dashboard`	`"Accounts"`

Example request

List all account segments.

GraphQL query

query GetSegments($input: GetSegmentsRequest!) {
  getSegments(input: $input) {
    segments {
      id
      name
      systemName
      description
      isSystem
      type
      entityType
    }
  }
}

Variables (JSON)

{
  "input": {
    "entityType": "Accounts"
  }
}

cURL

Run this from your terminal to test the API (replace YOUR_API_KEY as needed).

curl --location 'https://api.app.thrivestack.ai/growth-intelligence' \
--header 'content-type: application/json' \
--header 'x-api-key: YOUR_API_KEY' \
--data '
{
  "query": "query GetSegments($input: GetSegmentsRequest!) { getSegments(input: $input) { segments { id name systemName description isSystem type entityType } } }",
  "variables": {
    "input": {
      "entityType": "Accounts"
    }
  }
}
'

Example response

The response wraps segments in data.getSegments.segments[].

{
  "data": {
    "getSegments": {
      "segments": [
        {
          "id": "85b6e32e-c935-41d0-842c-88fd87f5bd64",
          "name": "All Account List",
          "systemName": "all_account_list",
          "description": "Shows a complete list of all accounts without filtering.",
          "isSystem": true,
          "type": "filtered",
          "entityType": "Accounts"
        },
        {
          "id": "51de5bca-7d9e-4a9f-9ee2-47963a789dc7",
          "name": "Enterprise Accounts",
          "systemName": "enterprise_accounts",
          "description": "Accounts with 250+ employees — large enterprise-level organizations.",
          "isSystem": true,
          "type": "filtered",
          "entityType": "Accounts"
        }
      ]
    }
  }
}

Tips and best practices

Apply a segment by reference. Pass a segment's id or systemName to the segmentId input on GetAccounts or GetUsers to fetch the records that match its saved filters.
Match entityType to the endpoint. Use Accounts segments with GetAccounts and Users segments with GetUsers.
Only filtered segments are applicable. Segments with type: "curated" are manually-maintained lists and are not yet supported by the segmentId input — they return an error.
Prefer systemName. It is stable and human-readable, whereas name can be edited.