Sign in Start free

How ApiTraffic works

The ApiTraffic model: accounts, roles, environments, buckets, requests, spans, firewall verdicts, redaction, exclusions, retention and tokens.

This page as Markdown

ApiTraffic records one record per API request. A middleware inside your application captures each request and response, times the work inside it, screens it with the firewall, and ships the result to ApiTraffic, where you search it, chart it and hand it to your AI agent. This page explains the pieces you will meet everywhere else in the docs.

How data flows

mermaid
flowchart LR
  subgraph app["Your application"]
    SDK["ApiTraffic SDK: capture, redaction at API, exclusions, firewall, APM spans"]
  end
  SDK -- "requests, spans and host samples (ingest token)" --> Ingest["ApiTraffic ingest"]
  Ingest --> Platform["ApiTraffic: processing, redaction at server, storage, endpoints, drift"]
  Platform -- "settings, rules and policies, pushed live" --> SDK
  Platform --> UI["Web app"]
  Platform --> API["REST API"]
  Platform --> MCP["MCP server for AI agents"]
  1. Your app and the SDK. @apitraffic/node (or the Strapi plugin) runs inside your process. It captures each inbound request and the outbound calls made while serving it, applies your Redact at API rules and exclusions, evaluates the firewall policy, and records APM spans if you set up performance monitoring. Capture never holds up your response: payloads are queued and sent in the background.
  2. Ingest. The SDK sends batches to ingest.apitraffic.io, authenticated with an ingest token. If your account has no active subscription, or a hard-capped allowance is used up, ingest refuses the traffic (see Plans, usage and retention).
  3. ApiTraffic. Requests are processed, Redact at server rules are applied before anything is saved, paths are grouped into endpoints, and drift and attention signals are computed.
  4. Settings flow back. Redaction rules, exclusions, firewall policies and capture settings are pushed to every connected SDK as you save them. Changing them never needs a deploy.
  5. You read it in the web app, through the REST API, or from an AI agent through the MCP server.

If ApiTraffic is unreachable, your application keeps serving traffic. See If ApiTraffic is unreachable.

Account, team and roles

An account is your organization in ApiTraffic. It holds the buckets, environments, team, plan and billing.

Everyone on the account has one of three roles:

Role Can do
Owner Everything, including billing, support access, purging data and closing the account. The person who signs up is the owner.
Admin Everything except the owner-only actions: invite and remove people, create and revoke tokens, generate embed tokens, manage redaction rules, exclusions and firewall policies, change account settings and the MFA policy, turn on SQL parameter and concrete Redis key capture, delete buckets and environments, connect Git providers and manage webhooks.
Member Use the product: read everything; create and edit buckets and bucket settings, stream views, collections, share links, workflows, endpoint rules and events. Members cannot create tokens or generate embed tokens, change redaction rules, exclusions, firewall policies or the MFA policy, or turn on SQL parameter or concrete Redis key capture (they can turn those off).

The full permission table is in Team and roles.

Environments

An environment is a stage your software runs in, such as production, staging or development. Environments are account-wide: every bucket can receive traffic from every environment, and the environment menu at the top of the app filters what you see.

Traffic is tagged with an environment by the token that sent it, because every ingest token belongs to one environment. To send staging traffic, create an ingest token in the staging environment and use it in your staging deployment. Each account has one default environment, which cannot be deleted. See Environments.

Buckets

A bucket holds the traffic of one application or service. Each bucket has its own request log, endpoints, dashboards and settings (Bucket Settings: endpoint handling, drift detection, APM capture, host telemetry and more). New accounts start with Default Bucket.

Use one bucket per service, so metrics and endpoints stay separate. Your plan may limit how many buckets and environments you can create. See Buckets.

Requests: inbound and outbound

A request is one record of an HTTP exchange: method, URL, query, headers, request and response bodies, status code, timing, tags and traces you add in code, the firewall verdict, and the APM spans recorded while it ran.

  • Inbound requests are the calls your API receives.
  • Outbound requests are the calls your application makes to other APIs while serving one. The SDK captures them by default and links each to the inbound request that caused it, so a slow checkout shows the slow payment call inside it. See Outbound requests.

All Traffic shows both; Inbound Traffic and Outbound Traffic show one direction each.

Bodies are capped at 512 KB each by default (maxBodyBytes). Credential-shaped body keys and query parameters (such as password, token and secret) are masked by default.

Captures

A capture is a request you send to a bucket’s capture URL so you can inspect it without forwarding it anywhere, for example to see a webhook’s payload. Captures have no response and are listed under Workspace → Captures in the left navigation, apart from your application’s traffic.

Endpoints

An endpoint is a route, such as GET /v1/orders/{order_id}, rather than a concrete path. With endpoint grouping on, ApiTraffic learns which path segments are IDs and collapses them, so metrics, drift and performance are reported per route. You can tune grouping per bucket and add your own endpoint rules. See Endpoint handling and Endpoint rules.

Spans and performance monitoring (APM)

A span is one timed piece of work inside a request: a database query, a cache call, a queue operation or an outbound HTTP call. The spans of a request form its waterfall, so you can see where the time went and which line of code issued the slow query. Spans come from OpenTelemetry instrumentation that the SDK starts for you, or from your own OpenTelemetry setup. See APM overview.

Firewall verdicts

The web application firewall (WAF) runs inside your application and scores each inbound request against the managed rule set and your policy’s own rules, lists and rate limits. Every request records the verdict, so you can search for what was blocked and why.

A policy runs in one of two modes: Monitor records what it would have blocked without affecting traffic, and Enforcing blocks it. Policies are created by owners and admins and pushed to running servers without a deploy. See Firewall overview.

Redaction

Redaction rules mask or remove sensitive values: card numbers, personal data, headers, JSON fields. Each rule runs in one of two places:

Location Where it runs Use it when
Redact at API Inside your process, before the data is sent. The value never leaves your server. Data must never reach ApiTraffic.
Redact at server In ApiTraffic, before the request is saved. The value may reach ApiTraffic but must not be stored, or the traffic is captured without the SDK.

Either way, everything that reads a stored request (the request log, share links, the API and the MCP server) sees only the redacted value. Workflows receive the request as captured, before Redact at server rules run, because they deliver to your own destination; values redacted at the API never leave your app, so workflows can’t receive those, and credential headers are always masked. The SDK does not send anything until your account’s redaction rules have loaded. Rules apply to requests captured after you save them; they do not change requests already stored. See Redactions.

Exclusions

An exclusion is a rule that stops matching requests from being captured at all, such as health checks or internal admin routes. Exclusions are evaluated in the SDK, so excluded requests are never sent and do not count toward your usage. See Exclusions.

Plans, usage and retention

Your plan decides which features you can use, how much traffic is included, and how long data is kept. Every new account starts on a trial.

  • Feature availability. Some areas depend on your plan, including collections, stream views, the firewall, APM, deploy and incident markers, share links, embeds, AI diagnoses, the MCP server, drift detection, attention signals, Git integrations and workflows. When your plan does not include one, its page shows an upgrade prompt and the API answers 403 with code 2221, naming the feature in data.feature.
  • Usage. We email you when an allowance reaches 80% and again at 100% in each billing period. Past an allowance, your plan either bills the extra at a published rate or stops capture until the period resets (ingest then answers 429). See Plan, usage and billing.
  • Retention. Request metadata is kept for your plan’s retention window, listed on the pricing page, and then expires. Captured bodies and APM spans have their own windows, so they can expire before the request record does.
  • No subscription. Once a trial has ended without a subscription, ingest can refuse new traffic with 402 until you choose a plan. Your application is not affected; only capture stops.

Tokens and credentials

Credential What it is for Where you get it Who can create it
Ingest token The SDK credential. Sends traffic and reads SDK settings, nothing else; it can’t mint embed tokens. Deploy it with your app, but keep it secret. Belongs to one environment. The setup page (Create ingest token) or Account → API Tokens, role Ingest Owner, admin
API token, Administrator or User role Scripts and integrations that call the REST API. Administrator acts as an admin, User as a member. Only Administrator tokens can mint embed tokens. Account → API Tokens Owner, admin
MCP token A static credential for MCP clients and unattended agents, limited to the environment and buckets you choose. Account → MCP Tokens Owner, admin
OAuth connection Signs an MCP client (Claude, Claude Code, Cursor, VS Code) in as you, with no token to copy. Limited to the environment and buckets you approve. Your MCP client starts it; manage connections under Account → Connected Apps Anyone, for themselves
Embed token A short-lived token for the embeddable request log, minted on your server with an Administrator API token. apitraffic.embedToken() in the SDK, with the Administrator token in API_TRAFFIC_EMBED_TOKEN Your server, with an Administrator token; owners and admins in Embed Setup

Token values are shown once, when they are created. See API tokens, MCP server and Connected apps and OAuth.

Sample data

Every account can show a read-only demo bucket, Sample: Acme Store API, in the environment Production (Sample). It receives live traffic from a fictional online store, with every feature populated, so you can explore before you install anything. It is not counted toward your plan or usage. See Sample data.