Segments
List segments in a workspace and page through their members.
Segments are groups of users or accounts that share a behaviour or attribute. Accoil creates a set of default segments automatically; you can also define your own.
Filter the list by scope to get just user or just account segments, and pass exclude_defaults=true to see only the segments you defined yourself. To read a segment's contents, use GET /v2/segments/{id}/members, which pages the same way as every other list endpoint.
BearerAuthAuthorizationBearer <token>API Token Authentication
All API requests require authentication via a Bearer token. Provide your API token in the Authorization header of each request.
Example: Authorization: Bearer accoil_YOUR_API_TOKEN
You can create and manage your API token by navigating to: Settings > Product Settings > API Token in the Accoil web app.
⚠️ Note: This API token is used only for reading data from the Accoil API. It is not the same as the
api_keyused for sending (ingesting) event data into Accoil.
workspace_id*integerThe workspace ID used to scope the request. You can find the workspace ID in the app URL:
https://app.accoil.com/48/scores/{workspace_id}/accounts/{id} Example: For the URL https://app.accoil.com/48/scores/123/accounts/154, the workspace_id is 123
Omitting it returns 400 (missing_workspace_id); a value that isn't a
positive integer returns 400 (invalid_workspace_id). A well-formed ID
that doesn't belong to your product returns 404
(workspace_id_not_found).
1 <= valuescope?stringFilter segments by scope (user or account)
"user""account"exclude_defaults?booleanWhen true, exclude default segments created automatically by Accoil
falselimit?integerMaximum number of results to return
1 <= value <= 10050offset?integerNumber of results to skip for pagination
0 <= value0Segments retrieved successfully
application/json- response
data*array<>_meta*curl -X GET 'https://api.accoil.com/v2/segments?workspace_id=1'{ "data": [ { "id": 0, "name": "string", "scope": "user", "default": true, "member_count": 0, "description": "string", "_links": { "property1": { "href": "string" }, "property2": { "href": "string" } } } ], "_meta": { "total_count": 0, "returned_count": 0, "limit": 0, "offset": 0, "workspace_id": 0, "product_id": 0 }}BearerAuthAuthorizationBearer <token>API Token Authentication
All API requests require authentication via a Bearer token. Provide your API token in the Authorization header of each request.
Example: Authorization: Bearer accoil_YOUR_API_TOKEN
You can create and manage your API token by navigating to: Settings > Product Settings > API Token in the Accoil web app.
⚠️ Note: This API token is used only for reading data from the Accoil API. It is not the same as the
api_keyused for sending (ingesting) event data into Accoil.
id*integerThe segment ID
workspace_id*integerThe workspace ID used to scope the request. You can find the workspace ID in the app URL:
https://app.accoil.com/48/scores/{workspace_id}/accounts/{id} Example: For the URL https://app.accoil.com/48/scores/123/accounts/154, the workspace_id is 123
Omitting it returns 400 (missing_workspace_id); a value that isn't a
positive integer returns 400 (invalid_workspace_id). A well-formed ID
that doesn't belong to your product returns 404
(workspace_id_not_found).
1 <= valueSegment retrieved successfully
application/json- response
data*_meta?Response-level metadata returned alongside the data payload on show
endpoints. Carries the workspace and product context needed to build
app deep-links (the app URL is also pre-computed on _links.app,
but the IDs are exposed for callers that want to construct their own).
curl -X GET 'https://api.accoil.com/v2/segments/0?workspace_id=1'{ "data": { "id": 0, "name": "string", "scope": "user", "default": true, "member_count": 0, "description": "string", "_links": { "property1": { "href": "string" }, "property2": { "href": "string" } } }, "_meta": { "workspace_id": 0, "product_id": 0 }}BearerAuthAuthorizationBearer <token>API Token Authentication
All API requests require authentication via a Bearer token. Provide your API token in the Authorization header of each request.
Example: Authorization: Bearer accoil_YOUR_API_TOKEN
You can create and manage your API token by navigating to: Settings > Product Settings > API Token in the Accoil web app.
⚠️ Note: This API token is used only for reading data from the Accoil API. It is not the same as the
api_keyused for sending (ingesting) event data into Accoil.
id*integerThe segment ID
workspace_id*integerThe workspace ID used to scope the request. You can find the workspace ID in the app URL:
https://app.accoil.com/48/scores/{workspace_id}/accounts/{id} Example: For the URL https://app.accoil.com/48/scores/123/accounts/154, the workspace_id is 123
Omitting it returns 400 (missing_workspace_id); a value that isn't a
positive integer returns 400 (invalid_workspace_id). A well-formed ID
that doesn't belong to your product returns 404
(workspace_id_not_found).
1 <= valuesort?stringSort field for members. For user-scoped segments one of: score,
name, last_seen, first_seen, activation_rate,
score_change, frequency. Account-scoped segments additionally
support active_users and total_users.
"score"order?stringSort order
"desc""asc""desc"limit?integerMaximum number of results to return
1 <= value <= 10050offset?integerNumber of results to skip for pagination
0 <= value0Segment members retrieved successfully
application/json- response
data*array<|>Each item is a slim view of a user (when the segment is
user-scoped) or an account (account-scoped). Read
_meta.segment_scope to know which shape applies. For
the full object — including trait expansions, segment
memberships, and the complete metric set — follow the
item's _links.self to /v2/users/:id or
/v2/accounts/:id.
_meta*curl -X GET 'https://api.accoil.com/v2/segments/0/members?workspace_id=1'{ "data": [ { "id": "string", "scope": "user", "name": "string", "tracking_id": "string", "email": "string", "display_name": "string", "metrics": { "engagement_score": 0.1, "score_change": 0.1, "activation_rate": 0.1, "last_seen": "2019-08-24" }, "_links": { "property1": { "href": "string" }, "property2": { "href": "string" } } } ], "_meta": { "total_count": 0, "returned_count": 0, "limit": 0, "offset": 0, "workspace_id": 0, "product_id": 0, "segment_id": 0, "segment_scope": "user" }}