# 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.

Source: https://dev.apitraffic.io/docs/api-reference/segments

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](#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

- **records (object[], required)**:
  The segments, as [segment objects](#the-segment-object).

## 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](#label-rules), `{ "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-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
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](#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](https://dev.apitraffic.io/docs/api-reference/buckets#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](https://dev.apitraffic.io/docs/api-reference/requests) 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](https://dev.apitraffic.io/docs/api-reference/reports)); `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](https://dev.apitraffic.io/docs/api-reference/reports).