Sign in Start free

Segments API

Create and change segments, groups of buckets you report on together, and search the traffic of every bucket in one, with the ApiTraffic REST API.

This page as Markdown

A segment is a named group of buckets, such as Checkout for the storefront, checkout and payments buckets. It holds no data and no settings: it is a scope. Reports, dashboards and traffic search can be scoped to a segment instead of one bucket, and they read the segment’s buckets as they are when they run, so a bucket added to a segment shows up in every dashboard on it without editing the dashboard.

Permissions: everyone on the account sees every segment. Any member, or a user or administrator API token, can create and change segments. Deleting one is for the person who created it, or an owner or admin (or an administrator API token). Segments need the Segments feature in your plan; listing, reading and deleting them stay possible if your plan drops it.

Connections limited to some buckets: an MCP connection chosen for some buckets that lists segments, reads a segment’s overview, or runs a report (saved or not) scoped to a segment reads only the segment’s buckets it may read; outsideAccess (on each segment listed, on the overview, and in a report result’s meta.scope) says how many it left out, and their names, services and traffic are never returned. A report on the whole account run through such a connection reads its buckets only, and says so the same way (meta.scope with buckets and outsideAccess, without a segment). REST API credentials read every bucket of the account, as they do everywhere else, so outsideAccess is always 0 for them.

The segment object

  • sid (string, required): The segment’s identifier (seg_ and 27 letters and digits).

  • name (string, required): The segment’s name (at most 120 characters).

  • description (string): What the segment is for.

  • defaultEnvironmentSid (string): The environment the segment opens in, usually production.

  • rule (object): The segment’s label rule, { "labels": { "system": "checkout" } }, or null. See label rules.

  • members (object[], required): The segment’s buckets, each with bucketSid, bucketName, services and source: manual for a bucket chosen for the segment, rule for one only its rule adds. services is "*" for the whole bucket, including services created later, or the services chosen (for a rule member, the services the rule matches), each with sid and name. A chosen bucket the rule matches too also has ruleServices, what the rule adds to it; the segment reads both.

  • outsideAccess (integer, required): How many of the segment’s buckets this credential cannot read. Always 0 on the REST API.

  • canDelete (boolean, required): Whether this caller may delete the segment.

  • createdBy (string): The person who created it (null when an API token did).

  • createdAt (string, required): When the segment was created (ISO 8601).

List segments

GET https://api.apitraffic.io/v1/accounts/{accountSid}/segments

Returns every segment on the account, sorted by name.

Query parameters

  • bucketSid (query, string): Only the segments that hold this bucket.

Response

Create a segment

POST https://api.apitraffic.io/v1/accounts/{accountSid}/segments

Body

  • name (body, string, required): The segment’s name.

  • description (body, string): What the segment is for.

  • defaultEnvironmentSid (body, string): One of the account’s environments.

  • rule (body, object): A label rule, { "labels": { "system": "checkout" } }: also include the buckets and services labelled with every pair.

  • members (body, object[]): Up to 200 buckets, each { "bucketSid": "..." } for the whole bucket, or { "bucketSid": "...", "serviceSids": ["svc_..."] } for up to 100 of its services. A chosen service that is later merged into another is read as the service it was merged into, and requests are matched to services the way the Services page matches them, so renames, new names and merges apply to all past traffic. Archived services cannot be newly chosen.

Answers 201 with the segment object. The number of segments an account can keep depends on the plan; past it, the answer is 409 ENTITLEMENT_LIMIT_REACHED.

bash
curl -X POST https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/segments \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Checkout", "members": [{"bucketSid": "bkt_storefront"}, {"bucketSid": "bkt_checkout"}, {"bucketSid": "bkt_payments"}]}'

Get a segment

GET https://api.apitraffic.io/v1/accounts/{accountSid}/segments/{segmentSid}

Returns the segment object.

Change a segment

PATCH https://api.apitraffic.io/v1/accounts/{accountSid}/segments/{segmentSid}

Send any of name, description, defaultEnvironmentSid, rule and members. rule: null removes the rule. members replaces the chosen members (source: manual); leave out the members the rule adds, which are never saved: sending one makes it a chosen member. A member the segment already holds, sent without serviceSids, keeps the services it holds; send "serviceSids": ["*"] to make it the whole bucket.

Label rules

A rule fills a segment from labels: { "labels": { "system": "checkout" } } adds every live bucket labelled with every pair as the whole bucket and, in a bucket that is not, every service labelled with them (its own labels, with its bucket’s value wherever both set a key), the bucket read narrowed to those services. Archived services and services merged into another are not added. A rule has 1 to 10 pairs, with keys and values checked as labels are; an invalid rule is refused with 400 (INVALID_PARAMETERS for the shape, SEGMENT_INVALID, code 2980, for a key or value).

The rule’s members are read whenever the segment is, by a report, a dashboard tile, a search or a GET: a bucket that gains the label is in all of them from then on, and one that loses it is out. A bucket chosen by hand that the rule also matches reads what either gives it. A connection limited to some buckets sees the rule’s members narrowed to them, as for any other member.

bash
curl -X PATCH https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/segments/seg_2mXq7RbT4kPz9WvN3cHd8LsYfQa \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"rule": {"labels": {"system": "checkout"}}}'

Add a bucket to a segment

POST https://api.apitraffic.io/v1/accounts/{accountSid}/segments/{segmentSid}/members

Adds one bucket ({ "bucketSid": "..." }, or with serviceSids for some of its services) and leaves the other members as they are. Adding a bucket the segment already holds, without serviceSids, changes nothing; with serviceSids it replaces what that member holds (["*"] makes it the whole bucket).

Delete a segment

DELETE https://api.apitraffic.io/v1/accounts/{accountSid}/segments/{segmentSid}

Answers 204. Reports and dashboards scoped to the segment stop running and say the segment was deleted until you give them another scope: they are never widened to the whole account. Only the creator, or an owner or admin, can delete a segment (otherwise 403, code 2983).

Search a segment’s traffic

GET https://api.apitraffic.io/v1/accounts/{accountSid}/segments/{segmentSid}/requests

The request list across every bucket in the segment: the same query parameters (criteria, environmentSid, startTime, endTime, limit, from), the same paging and the same request objects, each with its bucketSid. Stream views and services belong to one bucket, so streamViewSid and serviceSid are refused. The answer adds segment (sid, name), buckets (the buckets searched) and outsideAccess.

A segment’s overview

GET https://api.apitraffic.io/v1/accounts/{accountSid}/segments/{segmentSid}/overview

Without panel, answers panels (the overview’s panels, each with key, title, visualization and its report definition without a time range or scope) and securityPanel. With panel, runs one of them as a report on the segment and answers panel, definition and result (a report result); panel=deploys answers markers, the deployment events of the segment’s buckets in the window.

  • panel (query, string): summary, requests, errors, latency, endpoints, topErrors or deploys.

  • relative (query, string): A relative time range, such as last_24h (the default) or last_7d. Or send start and end (ISO 8601) instead.

  • environmentSid (query, string): Only this environment.

Every service

GET https://api.apitraffic.io/v1/accounts/{accountSid}/services

Every service of the buckets the credential can read, or of one segment (segmentSid) or bucket (bucketSid), with requests, errorRate, p95 and series (requests per interval of points) over the time range, running (instances running now), nodeVersions and lastDeploy (the latest deployment event on its bucket). Takes relative, start, end and environmentSid like the overview. Traffic numbers cover the 90 busiest services, and only scopes of at most 200 buckets: notes says what was left out, and a service without numbers has requests: null. The answer adds buckets and outsideAccess.

Reports and dashboards on a segment

A report’s or dashboard’s scope takes segmentSid in place of bucketSid:

json
{ "scope": { "segmentSid": "seg_2mXq7RbT4kPz9WvN3cHd8LsYfQa", "environmentSid": "a1b2c3" } }

A scope names one bucket or one segment, not both. When a dashboard’s or a viewer’s scope names a bucket, it replaces a report’s segment, and the other way round. Group by bucket_sid to split a segment’s numbers by bucket, or by service to split them by service. A result on a segment carries meta.scope: the segment, the buckets read and outsideAccess. See Reports.