togglddocs
Dashboard
GuidesAPI reference
Segments

Retrieve a segment

GET
/api/v1/segments/{key}

Returns a segment, its member count, and the keys of the flags that use it.

Requires a management key.

Returns 404 if no segment has this key.

Authorization

bearer
headerAuthorizationBearer <token>

Send a credential in the Authorization header: Authorization: Bearer <token>. Each credential belongs to one environment of one workspace, so the API never takes a workspace or environment in the URL.

  • Management key (ffk_…, secret): manages flags, segments, environments, and API keys, and reads the audit log and analytics. It can also do everything an evaluation key can.
  • Evaluation key (ffk_…, secret): for server SDKs. It evaluates flags, reads flag definitions for local evaluation, and sends telemetry.
  • Public token (ffp_…, not secret): for browser and mobile apps. It evaluates flags through OFREP and sends telemetry. It cannot read flag definitions.

Keep secret keys on your server. A 401 response means the credential is missing or not valid. A 403 response means the credential is valid but its role cannot perform the operation.

Path Parameters

key*string

The segment key, such as beta-testers.

Response Body

OK

application/json
  1. response

A reusable audience that targeting rules can reference. A subject is in the segment if it matches any rule or its key is in the member list. Segments belong to the workspace and apply in every environment.

key*string

The unique key of the segment in the workspace, such as beta-testers.

name?string

A display name for the segment.

description?string

A description of the audience.

keyAttribute*string

The evaluation context attribute compared with the member list. Defaults to targetingKey.

rules*array<>

Membership rules. A subject is in the segment if any rule matches.

listMode*string

How the member list reaches evaluation. none: the segment has no listed members. inline: members are sent with the flag definitions. remote is reserved for larger lists and is not used yet.

Value in"none""inline""remote"
memberCount*number|
version*number|
usedBy*array<string>

Keys of the flags whose targeting rules use this segment, in any environment.

createdAt*string

When the segment was created, as an ISO 8601 timestamp.

updatedAt*string

When the segment was last changed, as an ISO 8601 timestamp.

Example Request
curl -X GET 'https://api.toggld.io/api/v1/segments/string'
Example Response
{  "key": "beta-testers",  "name": "Beta testers",  "keyAttribute": "targetingKey",  "rules": [    {      "id": "staff",      "conditions": [        {          "attribute": "email",          "operator": "endsWith",          "value": "@example.com"        }      ]    }  ],  "listMode": "inline",  "memberCount": 2,  "version": 4,  "usedBy": [    "new-checkout"  ],  "createdAt": "2026-05-01T12:00:00.000Z",  "updatedAt": "2026-05-03T08:15:00.000Z"}

Create a segment POST

Creates a segment with optional membership rules. Add member keys afterwards with the update segment members endpoint. Requires a management key. Returns `409` if the key is already in use and `422` if the rules are not valid.

Update a segment PATCH

Changes the name, description, key attribute, or rules of a segment. Omitted fields keep their current values. The change applies to every flag that uses the segment, in every environment. Requires a management key. Returns `404` if no segment has this key, `409` if `expectedVersion` does not match the current version, and `422` if the rules are not valid.