# Stream views API

> List, create, update and delete stream views (named request filters on a bucket) and read the latest requests that match one.

Source: https://www.apitraffic.io/docs/api-reference/stream-views

A stream view is a saved, named filter on a bucket's requests, such as "Payment failures" or "Slow checkouts". Views appear as one-click filters in the request log, and they are what starts [workflows](https://www.apitraffic.io/docs/api-reference/workflows). See [Stream views](https://www.apitraffic.io/docs/traffic/saved-views) for using them in the app.

**Plan:** creating and changing views needs a plan that includes **Saved stream views**; the number of views an account can keep depends on the plan. Listing, reading and deleting existing views keep working if the plan changes. **Permissions:** any member, or a `user` or `administrator` API token.

## The stream view object

- **sid (string, required)**:
  The view's identifier (`sv_` followed by 27 letters and digits).

- **bucketSid (string, required)**:
  The bucket the view filters.

- **name (string, required)**:
  The view's name.

- **criteria (string, required)**:
  The filter, in the [search syntax](https://www.apitraffic.io/docs/traffic/search).

- **icon (string, required)**:
  `search`, `star`, `alert`, `check`, `bolt`, `bookmark`, `flag` or `heart`.

- **createdAt (string, required)**:
  When the view was created (ISO 8601).

- **updatedAt (string | null)**:
  When it was last changed.

- **deletedAt (string | null)**:
  `null` for an existing view.

## List stream views

`GET https://api.apitraffic.io/v1/accounts/{accountSid}/buckets/{bucketSid}/streamViews`

Returns every view on a bucket.

### Path parameters

- **accountSid (path, string, required)**:
  The account identifier.

- **bucketSid (path, string, required)**:
  The bucket identifier.

### Response

- **hasMore (boolean, required)**:
  Always `false`.

- **records (object[], required)**:
  The views, as [stream view objects](#the-stream-view-object).

```bash cURL
curl https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/buckets/k3m9p2x/streamViews \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN"
```

```js Node.js
const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const response = await fetch(`https://api.apitraffic.io/v1/accounts/${accountSid}/buckets/k3m9p2x/streamViews`, {
  headers: { Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}` },
});
const { records } = await response.json();
```

```json 200
{
  "hasMore": false,
  "records": [
    {
      "sid": "sv_2vC8xZ1aS3dF5gH7jK9lQ2wE4rT",
      "bucketSid": "k3m9p2x",
      "name": "Payment failures",
      "criteria": "status_code >= 500 AND url_path like \"/v1/payments/*\"",
      "icon": "alert",
      "createdAt": "2026-03-02T16:10:00.000Z",
      "updatedAt": null,
      "deletedAt": null
    },
    {
      "sid": "sv_2wD9yA2bT4eG6hJ8kL1mR3xF5sU",
      "bucketSid": "k3m9p2x",
      "name": "Slow checkouts",
      "criteria": "url_path == \"/v1/checkout\" AND duration >= 1000",
      "icon": "bolt",
      "createdAt": "2026-03-02T16:11:00.000Z",
      "updatedAt": null,
      "deletedAt": null
    }
  ]
}
```

## Get stream view

`GET https://api.apitraffic.io/v1/accounts/{accountSid}/buckets/{bucketSid}/streamViews/{streamViewSid}`

Returns one view.

### Path parameters

- **accountSid (path, string, required)**:
  The account identifier.

- **bucketSid (path, string, required)**:
  The bucket identifier.

- **streamViewSid (path, string, required)**:
  The view's identifier.

### Response

A [stream view object](#the-stream-view-object).

```bash cURL
curl https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/buckets/k3m9p2x/streamViews/sv_2vC8xZ1aS3dF5gH7jK9lQ2wE4rT \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN"
```

```js Node.js
const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const streamViewSid = 'sv_2vC8xZ1aS3dF5gH7jK9lQ2wE4rT';
const response = await fetch(
  `https://api.apitraffic.io/v1/accounts/${accountSid}/buckets/k3m9p2x/streamViews/${streamViewSid}`,
  { headers: { Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}` } },
);
const view = await response.json();
```

```json 200
{
  "sid": "sv_2vC8xZ1aS3dF5gH7jK9lQ2wE4rT",
  "bucketSid": "k3m9p2x",
  "name": "Payment failures",
  "criteria": "status_code >= 500 AND url_path like \"/v1/payments/*\"",
  "icon": "alert",
  "createdAt": "2026-03-02T16:10:00.000Z",
  "updatedAt": null,
  "deletedAt": null
}
```

## Create stream view

`POST https://api.apitraffic.io/v1/accounts/{accountSid}/buckets/{bucketSid}/streamViews`

Saves a filter as a view.

**Plan:** needs **Saved stream views**; past the plan's view limit, the API answers `409` with code `2213`.

### Path parameters

- **accountSid (path, string, required)**:
  The account identifier.

- **bucketSid (path, string, required)**:
  The bucket identifier.

### Body parameters

- **name (body, string, required)**:
  The view's name.

- **criteria (body, string, required)**:
  The filter, in the [search syntax](https://www.apitraffic.io/docs/traffic/search). At most 50 conditions, joined with `AND` (criteria with ` OR ` are refused), each value at most 1024 characters. `like` values are globs that match the whole value, so `url_path like "/v1/payments/*"` matches every path under `/v1/payments/`.

- **icon (body, string)**:
  `search`, `star`, `alert`, `check`, `bolt`, `bookmark`, `flag` or `heart`.

### Response

The new [stream view object](#the-stream-view-object).

```bash cURL
curl -X POST https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/buckets/k3m9p2x/streamViews \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cart validation errors",
    "criteria": "url_path like \"/v1/cart/*\" AND status_code >= 400 AND status_code < 500",
    "icon": "search"
  }'
```

```js Node.js
const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const response = await fetch(`https://api.apitraffic.io/v1/accounts/${accountSid}/buckets/k3m9p2x/streamViews`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Cart validation errors',
    criteria: 'url_path like "/v1/cart/*" AND status_code >= 400 AND status_code < 500',
    icon: 'search',
  }),
});
const view = await response.json();
```

```json 200
{
  "sid": "sv_2xE1zB3cU5fH7jK9lM2nS4yG6tV",
  "bucketSid": "k3m9p2x",
  "name": "Cart validation errors",
  "criteria": "url_path like \"/v1/cart/*\" AND status_code >= 400 AND status_code < 500",
  "icon": "search",
  "createdAt": "2026-10-20T11:20:00.000Z",
  "updatedAt": null,
  "deletedAt": null
}
```

## Update stream view

`PUT https://api.apitraffic.io/v1/accounts/{accountSid}/buckets/{bucketSid}/streamViews/{streamViewSid}`

Replaces a view's name, criteria and icon. Workflows that use the view follow its new criteria.

**Plan:** needs **Saved stream views**.

### Path parameters

- **accountSid (path, string, required)**:
  The account identifier.

- **bucketSid (path, string, required)**:
  The bucket identifier.

- **streamViewSid (path, string, required)**:
  The view's identifier.

### Body parameters

- **name (body, string, required)**:
  The view's name.

- **criteria (body, string, required)**:
  The filter, with the same limits as [Create stream view](#create-stream-view).

- **icon (body, string)**:
  The icon.

### Response

The updated [stream view object](#the-stream-view-object), plus:

- **warnings (object[])**:
  Present when the view was saved before `like` meant a whole-value glob, a workflow uses it, and you changed its criteria: each entry (`code`, `condition`, `glob`, `message`) names a `like` condition whose meaning changed for those workflows. Check that they still start on the requests you expect.

```bash cURL
curl -X PUT https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/buckets/k3m9p2x/streamViews/sv_2wD9yA2bT4eG6hJ8kL1mR3xF5sU \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Slow checkouts",
    "criteria": "url_path == \"/v1/checkout\" AND duration >= 2000",
    "icon": "bolt"
  }'
```

```js Node.js
const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const streamViewSid = 'sv_2wD9yA2bT4eG6hJ8kL1mR3xF5sU';
const response = await fetch(
  `https://api.apitraffic.io/v1/accounts/${accountSid}/buckets/k3m9p2x/streamViews/${streamViewSid}`,
  {
    method: 'PUT',
    headers: {
      Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: 'Slow checkouts',
      criteria: 'url_path == "/v1/checkout" AND duration >= 2000',
      icon: 'bolt',
    }),
  },
);
const view = await response.json();
```

```json 200
{
  "sid": "sv_2wD9yA2bT4eG6hJ8kL1mR3xF5sU",
  "bucketSid": "k3m9p2x",
  "name": "Slow checkouts",
  "criteria": "url_path == \"/v1/checkout\" AND duration >= 2000",
  "icon": "bolt",
  "createdAt": "2026-03-02T16:11:00.000Z",
  "updatedAt": "2026-10-20T11:25:00.000Z",
  "deletedAt": null
}
```

## Delete stream view

`DELETE https://api.apitraffic.io/v1/accounts/{accountSid}/buckets/{bucketSid}/streamViews/{streamViewSid}`

Deletes a view.

### Path parameters

- **accountSid (path, string, required)**:
  The account identifier.

- **bucketSid (path, string, required)**:
  The bucket identifier.

- **streamViewSid (path, string, required)**:
  The view's identifier.

### Response

- **sid (string, required)**:
  The deleted view's identifier.

- **deleted (boolean, required)**:
  `true`.

```bash cURL
curl -X DELETE https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/buckets/k3m9p2x/streamViews/sv_2xE1zB3cU5fH7jK9lM2nS4yG6tV \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN"
```

```js Node.js
const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const streamViewSid = 'sv_2xE1zB3cU5fH7jK9lM2nS4yG6tV';
await fetch(`https://api.apitraffic.io/v1/accounts/${accountSid}/buckets/k3m9p2x/streamViews/${streamViewSid}`, {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}` },
});
```

```json 200
{
  "sid": "sv_2xE1zB3cU5fH7jK9lM2nS4yG6tV",
  "deleted": true
}
```

## Get latest matching requests

`GET https://api.apitraffic.io/v1/accounts/{accountSid}/buckets/{bucketSid}/streamViews/{streamViewSid}/requests`

Returns the five most recent requests that match the view, in full, with JSON bodies parsed. This is the sample data a workflow builder shows when you design a workflow for the view.

### Path parameters

- **accountSid (path, string, required)**:
  The account identifier.

- **bucketSid (path, string, required)**:
  The bucket identifier.

- **streamViewSid (path, string, required)**:
  The view's identifier.

### Response

- **records (object[], required)**:
  Up to five [request objects](https://www.apitraffic.io/docs/api-reference/requests#the-request-object), newest first, each with bodies and a `triggerData` object carrying the `streamViewSid`.

```bash cURL
curl https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/buckets/k3m9p2x/streamViews/sv_2vC8xZ1aS3dF5gH7jK9lQ2wE4rT/requests \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN"
```

```js Node.js
const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const streamViewSid = 'sv_2vC8xZ1aS3dF5gH7jK9lQ2wE4rT';
const response = await fetch(
  `https://api.apitraffic.io/v1/accounts/${accountSid}/buckets/k3m9p2x/streamViews/${streamViewSid}/requests`,
  { headers: { Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}` } },
);
const { records } = await response.json();
```

```json 200
{
  "records": [
    {
      "sid": "req_2nA8fK3pQ7xV1mZ5tR9wB4cL6hY",
      "bucketSid": "k3m9p2x",
      "environmentSid": "prd7k2",
      "direction": "in",
      "createdAt": "2026-10-19T14:21:07.412Z",
      "endpoint": "/v1/payments/{payment_id}/capture",
      "request": {
        "method": "POST",
        "path": "/v1/payments/pi_3f9a1c7e2b4d6a/capture",
        "body": { "amount": 8450, "currency": "usd" }
      },
      "response": {
        "statusCode": 502,
        "body": { "error": "upstream_timeout" }
      },
      "triggerData": { "streamViewSid": "sv_2vC8xZ1aS3dF5gH7jK9lQ2wE4rT" }
    }
  ]
}
```

The example shortens the request object; see [Get request](https://www.apitraffic.io/docs/api-reference/requests#get-request) for every field.

## Errors

| Status | Code | Meaning |
| --- | --- | --- |
| `400` | `1000` | A field is missing or invalid, for example `criteria` that cannot be parsed, with more than 50 conditions, or an unknown `icon`. |
| `400` | `2007` | The view's criteria could not be run (latest matching requests). |
| `403` | `2221` | The plan does not include stream views (create and update). |
| `403` | `2509` | Changing a view on the read-only sample bucket. |
| `404` | `4000` | No view with that sid in this bucket. |
| `409` | `2213` | The plan's stream view limit is reached. |

## Related

- [Stream views](https://www.apitraffic.io/docs/traffic/saved-views):
    Use views in the request log.

- [Workflows API](https://www.apitraffic.io/docs/api-reference/workflows):
    Run an automation when a view matches.