# How your data is organized

> Accounts, environments, buckets, services, endpoints, tags and labels: what each one is, what it belongs to, and how a request is filed.

Source: https://www.apitraffic.io/docs/data-model

Every request ApiTraffic records is filed under three things: the **account** it belongs to, the **bucket** (the application or service that handled it) and the **environment** (the stage it ran in, such as production). Everything else, from endpoints and dashboards to alerts and firewall policies, is organized around those three. This page explains each object, how they fit together, and how to lay out your own services.

For what each feature does, see [How ApiTraffic works](https://www.apitraffic.io/docs/concepts).

## The hierarchy at a glance

```mermaid
flowchart TD
  Account["Account: your organization"]
  Account --> Envs["Environments: Production, Staging, Development"]
  Account --> Buckets["Buckets: one per service, such as Checkout API"]
  Account --> Rules["Account rules: redactions, exclusions, firewall policies, endpoint rules, alert routes"]
  Account --> Shared["Team, plan, tokens, tag keys, reports and dashboards"]
  Envs --> Stream["A bucket in one environment: Checkout API in Production"]
  Buckets --> Stream
  Stream --> Requests["Requests, inbound and outbound"]
  Stream --> Servers["Servers running the SDK"]
  Requests --> Endpoints["Grouped into endpoints, such as GET /v1/orders/{order_id}"]
  Requests --> Spans["Spans: queries, cache calls, outbound calls"]
  Requests --> Tags["Tags you add in code, such as customerId"]
```

Environments and buckets are both directly under the account, and neither contains the other. They cross: every bucket can receive traffic from every environment. Picking a bucket in the bucket menu and an environment in the environment menu, both in the top bar, gives you one stream of traffic, for example **Checkout API** in **Production**. Almost every page in the app shows that one stream.

|  | Production | Staging | Development |
|---|---|---|---|
| **Checkout API** | Checkout API in Production | Checkout API in Staging | Checkout API in Development |
| **Admin API** | Admin API in Production | Admin API in Staging | Admin API in Development |

## Each object

| Object | What it is | Belongs to | How it is set |
|---|---|---|---|
| **Account** | Your organization. Holds everything below, plus the team, plan and billing. | - | Created when you sign up |
| **Environment** | A stage your software runs in: production, staging, development. | Account | By the ingest token the SDK sends with |
| **Bucket** | One application or service, with its own request log, endpoints, dashboards, servers and settings. | Account | By the bucket ID the SDK is configured with (`API_TRAFFIC_BUCKET`) |
| **Request** | One recorded HTTP exchange, inbound (received by your API) or outbound (made by your API). | One bucket and one environment | Captured by the SDK |
| **Endpoint** | A route, such as `GET /v1/orders/{order_id}`, that groups requests whose paths differ only by IDs. | Bucket | Learned from traffic, or set by [endpoint rules](https://www.apitraffic.io/docs/data/endpoint-rules) |
| **Span** | One timed piece of work inside a request: a query, a cache call, an outbound call. | Request | Recorded by the SDK's [APM](https://www.apitraffic.io/docs/apm/overview) |
| **Server** | One process running the SDK, with its health and labels. | Bucket and environment | Reported by the SDK |
| **Tag** | A key and value you attach to a request in code, such as `customerId=org_8f2a`. | Request (its key is registered on the account as a dimension) | `apitraffic.tag()` in your code |

## How a request is filed

When the SDK sends a request to ApiTraffic, two settings decide where it lands:

| Setting | Decides | Example |
|---|---|---|
| `API_TRAFFIC_TOKEN`, the ingest token | The **account** and the **environment**. Every ingest token belongs to one environment. | A token created on the **Staging Tokens** card files traffic under Staging. |
| `API_TRAFFIC_BUCKET`, the bucket ID | The **bucket**. Seven lowercase letters and digits, shown on the setup page and in **Bucket Settings**. | `k3m9p2x` files traffic under the bucket with that ID. |

The bucket must belong to the same account as the token, or the traffic is refused. An ingest token isn't tied to a bucket, so services running in the same environment can share one token and differ only in `API_TRAFFIC_BUCKET`. Giving each service its own token lets you revoke one without touching the others.

So the same code, deployed twice, reports to two environments when each deployment has a token from a different environment:

```bash
# Production deployment of the checkout service
API_TRAFFIC_TOKEN=<ingest token from the Production card>
API_TRAFFIC_BUCKET=k3m9p2x

# Staging deployment of the same service
API_TRAFFIC_TOKEN=<ingest token from the Staging card>
API_TRAFFIC_BUCKET=k3m9p2x
```

Requests sent to a bucket's **capture URL** instead of through the SDK are filed by the URL itself: each bucket has one capture URL per environment, listed in **Bucket Settings**. See [Captures](https://www.apitraffic.io/docs/traffic/request-log#captures).

## Services

ApiTraffic has no separate "service" object. The word appears in two places, and they mean different things:

- **A bucket is how you model a service.** Create one bucket per application or service you run, so that each keeps its own endpoints, metrics, alerts and settings. When the docs say "one bucket per service", this is what they mean.
- **The Service server label** is a name each SDK process reports about itself, read from `API_TRAFFIC_SERVICE_NAME` (or `SERVICE_NAME`, `K_SERVICE`, `FLY_APP_NAME`). It is shown on the [Servers page](https://www.apitraffic.io/docs/integrations/servers), and `API_TRAFFIC_SERVICE_NAME` is also the service name reported to OpenTelemetry. It doesn't decide which bucket traffic goes to; only `API_TRAFFIC_BUCKET` does.

In most setups the two match: the checkout service sends to the **Checkout API** bucket and reports itself as `checkout-api`. If several processes report to one bucket (for example an API and a background worker), the Service label tells them apart on the Servers page.

## Labels, tags and names

Several features attach extra information to your data. They are easy to mix up, so here is what each one describes:

| Term | Describes | Set by | Where you use it |
|---|---|---|---|
| **Tag** | One request: who made it, which plan, which feature flag. Up to 32 per request. | `apitraffic.tag('customerId', id)` in your code | Search, [reports](https://www.apitraffic.io/docs/reports) and [dashboards](https://www.apitraffic.io/docs/dashboards). See [Tags and dimensions](https://www.apitraffic.io/docs/tags). |
| **Dimension** | A tag key, as registered on the account. Each key you send becomes one. | Created automatically from your tags | **Account** → **Settings** → **Dimensions**: give it a display name, classify it, choose the customer key, promote it |
| **Catalogue label** | One tag value: a readable name for an ID, such as `Acme Corp` for `org_8f2a`, with optional attributes. | Owners and admins, by hand, CSV upload or the [Dimensions API](https://www.apitraffic.io/docs/api-reference/dimensions) | Reports and dashboards show the label instead of the raw value |
| **Server labels** | One SDK process: **Service**, **Service version**, **Region** and **Commit**. | Environment variables on the server. See [Server labels](https://www.apitraffic.io/docs/integrations/configuration#server-labels). | The [Servers page](https://www.apitraffic.io/docs/integrations/servers) and each server's detail |
| **Event** | Something that happened at a point in time: a deploy, an incident, a config change. | You, the [Events API](https://www.apitraffic.io/docs/api-reference/events) or the MCP server | Markers on charts, scoped to buckets and environments. See [Events](https://www.apitraffic.io/docs/events). |

The short version: **tags describe requests, server labels describe servers, and catalogue labels describe tag values.**

## Where settings and rules live

Some things are configured once for the account and then aimed at buckets and environments; others live inside a single bucket.

**Account-level, targeted at buckets and environments.** Each rule applies to all buckets and environments, or only the ones you pick. For redactions, exclusions and the firewall, each bucket also has a read-only page listing the rules that apply to it.

| Rule | Targeting | Details |
|---|---|---|
| [Redactions](https://www.apitraffic.io/docs/data/redactions) | Buckets and environments | Every matching rule applies. |
| [Exclusions](https://www.apitraffic.io/docs/data/exclusions) | Buckets and environments | Every matching rule applies. |
| [Firewall policies](https://www.apitraffic.io/docs/waf/policies) | Buckets and environments | One policy runs per server: the most specific one covering its bucket and environment. |
| [Endpoint rules](https://www.apitraffic.io/docs/data/endpoint-rules) | Buckets, environments and direction | Tried in priority order. |
| [Alert routes](https://www.apitraffic.io/docs/alerts/routing) | Buckets and environments | None ticked means all. |
| [Events](https://www.apitraffic.io/docs/events) | Buckets and environments | All of them by default. |

**Bucket-level.** These belong to one bucket and are not shared with other buckets.

| Object | Notes |
|---|---|
| [Bucket Settings](https://www.apitraffic.io/docs/account/buckets#open-bucket-settings) | Endpoint handling, APM capture, host telemetry and drift detection. They apply in every environment. |
| [Endpoints](https://www.apitraffic.io/docs/endpoint-handling) | Learned from the bucket's own traffic. |
| [Collections](https://www.apitraffic.io/docs/collections) | Hold requests from their bucket only. |
| [Stream views](https://www.apitraffic.io/docs/traffic/saved-views) | A saved search over the bucket's traffic. |
| [Workflows](https://www.apitraffic.io/docs/workflows) | Attached to a stream view in one bucket, and fire for one environment. |
| [Servers](https://www.apitraffic.io/docs/integrations/servers) | Listed per bucket and environment. |

**Account-wide.** These cover every bucket and environment.

| Object | Notes |
|---|---|
| Team and roles | One role per person for the whole account. See [Team and roles](https://www.apitraffic.io/docs/account/team). |
| Plan, usage and billing | Usage is counted across all buckets and environments. |
| Tag keys and the catalogue | One registry and one customer key per account. |
| [Reports](https://www.apitraffic.io/docs/reports) and [dashboards](https://www.apitraffic.io/docs/dashboards) | Read every bucket and environment unless you narrow their scope. |
| Database query text and client IP addresses | Account-wide privacy settings on **Account** → **Profile**. |

## Who can reach what

Credentials are scoped by environment, and some also by bucket:

| Credential | Scope |
|---|---|
| **Ingest token** | One environment. Can send to any bucket in the account. |
| **API token** | Belongs to one environment and acts as an admin (**Administrator**) or a member (**User**). |
| **MCP token** and **OAuth connection** | One environment, and all of its buckets or only the ones you choose. |

Team members see every bucket and environment in the account. See [API tokens](https://www.apitraffic.io/docs/account/api-tokens) and [MCP server](https://www.apitraffic.io/docs/integrations/mcp-server#token-and-connection-scope).

## Lay out your own services

**One API in production and staging**

One bucket, such as **Store API**. Two environments, **Production** and **Staging**, each with its own ingest token. Both deployments use the same `API_TRAFFIC_BUCKET`.

**Several services that call each other**

One bucket per service: **Checkout API**, **Inventory API**, **Payments API**. Each deployment sets its own `API_TRAFFIC_BUCKET` and, ideally, `API_TRAFFIC_SERVICE_NAME`. Calls between them show up as outbound requests in the caller's bucket and inbound requests in the callee's, and requests that share a trace ID are joined on the **Distributed Trace** tab.

**A multi-tenant SaaS API**

One bucket for the API, not one per customer. Tag each request with the customer, for example `apitraffic.tag('customerId', org.id)`, and mark that key as the customer key in **Dimensions**. Reports, dashboards and searches can then be filtered or grouped by customer. Buckets count toward your plan's bucket limit, while a new customer is only a new tag value.

**The same API in several regions**

One bucket and one environment. Set `API_TRAFFIC_REGION` (or let the SDK read `AWS_REGION`, `FLY_REGION` and similar) so each server is labelled with its region. Use separate environments only if regions are separate stages that should never mix in dashboards and alerts.

**An API and its background workers**

The SDK records the HTTP requests a process receives and the outbound calls it makes while serving them. If your workers also serve HTTP (for example a webhook receiver), they can share the API's bucket: give each process a different `API_TRAFFIC_SERVICE_NAME` so the Servers page tells them apart. Use a second bucket if you want separate endpoints, alerts and settings for them.

### Bucket, environment, tag or label?

| You want to separate... | Use |
|---|---|
| Different applications or services, each with its own endpoints and settings | A **bucket** |
| Production from staging, so test traffic never reaches production dashboards and alerts | An **environment** |
| Requests by customer, plan, feature flag or anything else known while handling the request | A **tag** |
| Servers by service name, version, region or commit | **Server labels** |
| Moments in time, such as deploys and incidents | An **event** |

## Troubleshooting

**My staging traffic shows up in Production**

The staging deployment is using an ingest token from the Production card. Create a token on the Staging card of **API Tokens** and deploy staging with it.

**Two services are mixed together in one bucket**

Both deployments have the same `API_TRAFFIC_BUCKET`. Create a bucket for the second service and set its ID on that service. Requests already stored stay where they were filed.

**I set API_TRAFFIC_SERVICE_NAME but traffic still goes to the same bucket**

That is expected. The service name labels the server; only `API_TRAFFIC_BUCKET` chooses the bucket.

**I can't find my traffic**

Check both menus in the top bar. The bucket menu must show the bucket your app's `API_TRAFFIC_BUCKET` names, and the environment menu the environment of its ingest token.

## Related

- [Buckets](https://www.apitraffic.io/docs/account/buckets):
    Create buckets and change their settings.

- [Environments](https://www.apitraffic.io/docs/account/environments):
    Create environments and their tokens.

- [Tags and dimensions](https://www.apitraffic.io/docs/tags):
    Add your own context to requests.

- [SDK configuration](https://www.apitraffic.io/docs/integrations/configuration):
    Every SDK option, including server labels.
