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.

This page as Markdown

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.

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
Span One timed piece of work inside a request: a query, a cache call, an outbound call. Request Recorded by the SDK’s APM
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.

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, 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 and dashboards. See Tags and dimensions.
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 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. The Servers page 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 or the MCP server Markers on charts, scoped to buckets and environments. See 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 Buckets and environments Every matching rule applies.
Exclusions Buckets and environments Every matching rule applies.
Firewall policies Buckets and environments One policy runs per server: the most specific one covering its bucket and environment.
Endpoint rules Buckets, environments and direction Tried in priority order.
Alert routes Buckets and environments None ticked means all.
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 Endpoint handling, APM capture, host telemetry and drift detection. They apply in every environment.
Endpoints Learned from the bucket’s own traffic.
Collections Hold requests from their bucket only.
Stream views A saved search over the bucket’s traffic.
Workflows Attached to a stream view in one bucket, and fire for one environment.
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.
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 and 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 and MCP server.

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.