Sign in Start free

Dimensions

Tag keys, their classification and promotion, the customer catalogue and dropped-tag diagnostics

This page as Markdown

The dimensions API manages what Settings → Dimensions shows: the tag keys your SDKs send, the customer catalogue that names their values, and why tags were dropped. Every path is scoped to an account, and an account can only reach its own records.

Permissions. Any member can list keys, read the catalogue and diagnostics, and set a key’s display name, description and hidden flag. Changing a key’s classification or role, promoting and demoting, and changing the catalogue need an owner or admin (or an API token with the administrator role). Ingest tokens can’t use this API.

Personal values. For a key classified personal, values and labels are masked (d***@acme.com) unless the caller may view personal tags (owners and admins). This applies to catalogue entries (each has masked: true) and to the breakdown (meta.masked: true). A masked catalogue list returns the first page only: search and after are refused with a 400, since they would let hidden values be tested.

MCP. The list_dimensions and get_dimension_values MCP tools need the Custom reports plan feature; this REST API’s listing does not. list_dimensions also returns the suggestions, as suggestedToPromote, unless it is called with includeSuggestions: false (for when only the keys are needed: the saved reports and dashboards are then not read).

All examples use Authorization: Bearer . {key} is the tag key as your SDK sends it.

Tag keys

GET https://api.apitraffic.io/v1/accounts/{accountSid}/dimensions

List every registered key: the customer key first, then by share of requests.

  • include (query, string): suggestions to also return the keys suggested to promote (suggestions). Working them out reads the account’s saved reports and dashboards, so they are left out unless asked for

Response

  • records (array): The keys. Each has key, displayName, description, classification (none, pseudonymous, personal or secret), suggestedClassification, role (customer or none), hidden, promoted, promotionStatus (pending, backfilling, live, over_budget, demoted or null), promotedAt, promotedBy, firstSeenAt, lastSeenAt, catalogValues, and stats: distinct1d, distinct7d, requestShare7d (0 to 1), requests7d and updatedAt (all null until the nightly scan has run).

  • limits (object): maxKeys (keys the registry holds per account), registered, promoted (keys promoted now) and maxPromoted (your plan’s allowance of promoted keys; null when it is unlimited). maxPromoted is sent to the account owner only; anyone else, and every API token, gets promotedAtLimit (true when no more keys can be promoted) in its place

  • unregistered (object): Keys past the limit in the last 7 days: tags7d (how many tags used them) and up to 10 sampleKeys

  • suggestions (array): Only with include=suggestions. Keys suggested to promote, most used first (up to 20; empty when your plan does not include Custom reports): keys that are not promoted or classified secret, which the account’s saved reports and dashboards would read from pre-aggregated data once promoted. Each has key, reports (saved reports it would make fast), dashboards (dashboards with at least one such tile, with the dashboard’s own filter and scope applied) and requestShare7d. A report counts only when it groups by the key and everything else in it is held in pre-aggregated data: a key a report only filters on is not counted. Every report and dashboard in the account counts, including ones private to other people, but only the numbers are returned.

PATCH https://api.apitraffic.io/v1/accounts/{accountSid}/dimensions/{key}

Change a key. Send at least one field.

  • displayName (body, string): Up to 120 characters; "" clears it

  • description (body, string): Up to 1,000 characters; "" clears it

  • hidden (body, boolean): Hide the key from pickers and the list

  • classification (body, string): none, pseudonymous, personal or secret. Owners and admins only. A promoted key, or the customer key, cannot be secret

  • role (body, string): customer makes this the account’s customer key and takes the role from the key that had it; an unclassified key becomes pseudonymous. none removes the role. Owners and admins only

bash
curl -X PATCH https://api.apitraffic.io/v1/accounts/{accountSid}/dimensions/customerId \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{ "displayName": "Customer", "role": "customer" }'

Returns the key.

POST https://api.apitraffic.io/v1/accounts/{accountSid}/dimensions/{key}/promote

Promote a key to pre-aggregated reports. Needs the Custom reports plan feature and a free promoted-key slot: a full allowance answers 409 ENTITLEMENT_LIMIT_REACHED. A key classified secret can’t be promoted. Promoting a promoted key changes nothing, except at a full allowance, where the 409 comes first. Returns the key, with promotionStatus pending. New traffic is aggregated from about two minutes after promotion; history is backfilled newest day first (backfilling, with backfillProgress from 0 to 1), then the key is live. A key with more distinct values in a day than the plan aggregates is over_budget until the next UTC day.

POST https://api.apitraffic.io/v1/accounts/{accountSid}/dimensions/{key}/demote

Stop aggregating a key. Works on any plan. Returns the key, with promotionStatus demoted. The aggregates kept stay readable, and promoting the key again fills in only the time they do not cover.

GET https://api.apitraffic.io/v1/accounts/{accountSid}/dimensions/{key}/breakdown

A promoted key by value over a window, from its aggregates. Needs the Custom reports plan feature (reads keep working after a downgrade). The window is clamped to what aggregates keep: 13 months on Business and above, otherwise request retention, and request retention for a key classified personal; never past the account’s retention entitlement. A key classified secret is refused with a 400.

  • from (query, string): ISO 8601 window start. Default: 24 hours before to

  • to (query, string): ISO 8601 window end. Default: now

  • bucketSid (query, string): Only this bucket

  • environmentSid (query, string): Only this environment

  • limit (query, number): Values returned, by requests. Default 25, at most 500

Response

  • records (array): Per value: value, label and attributes (from the catalogue), requests, serverErrors, clientErrors, errorRate (server errors / requests), requestBytes, responseBytes, and latency (avgMs, p50Ms, p95Ms, maxMs, approximate: true; null when no request had a duration). Values past the per-minute limit are one record with value: "__other__" and other: true

  • coverage (object): The window’s requests, tagged (carried the key), other (counted as __other__), missing (no key), attributedShare and otherShare

  • window (object): from and to as read, and clamped when the window asked for started before what aggregates keep

  • meta (object): source: "aggregates", approximate, ready (false until the key’s aggregate source exists), promoted, promotionStatus, backfillProgress (0 to 1), coveredFrom (where backfilled history starts, once complete) and masked (when values are masked)

A failed read answers like other analytics reads: 504 TELEMETRY_TIMEOUT (narrow the window), 503 TELEMETRY_OVERLOADED with Retry-After, and so on.

Catalogue

GET https://api.apitraffic.io/v1/accounts/{accountSid}/dimensions/{key}/values

List a key’s catalogue entries, by value.

  • search (query, string): Matches values and labels containing this text (case-insensitive)

  • limit (query, number): Default 100, at most 500

  • after (query, string): The next value of the previous page

Response

  • records (array): Entries: value, label, attributes, source (api or csv), updatedAt, and masked when masked

  • hasMore (boolean): Whether there are more entries

  • next (string): Pass as after for the next page

PUT https://api.apitraffic.io/v1/accounts/{accountSid}/dimensions/{key}/values

Add or replace up to 1,000 entries. Safe to repeat. If any entry is invalid, nothing is saved, and the 400 lists each one in data.errors (index and error).

  • values (body, array, required): Entries: value (required; up to 255 characters), label (up to 255 characters), attributes (up to 20 strings, numbers or booleans, 4 KB in all; names follow the tag key rules)
bash
curl -X PUT https://api.apitraffic.io/v1/accounts/{accountSid}/dimensions/customerId/values \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{ "values": [ { "value": "org_8f2a", "label": "Acme Corp", "attributes": { "plan": "enterprise", "region": "eu" } } ] }'
json
{ "inserted": 1, "updated": 0 }

An account holds up to 1,000,000 entries; a write that would pass that is refused.

POST https://api.apitraffic.io/v1/accounts/{accountSid}/dimensions/{key}/values/upload

Add or replace entries from CSV text (up to 5 MB and 50,000 rows). The first row names the columns: value (required), label, and any others become attributes; a column named twice is refused. Invalid rows (including a row with more cells than the header) are skipped and reported. The valid rows are written all or nothing: if the file would take the catalogue past its limit, nothing is written. A value repeated in the file keeps its last row.

  • csv (body, string, required): The CSV text

  • dryRun (body, boolean): Check every row and return preview (the first 20 valid rows) without saving

Response

  • rows (number): Data rows in the file

  • valid (number): Rows that are (or would be) saved

  • invalid (number): Rows skipped

  • errors (array): Up to 100 skipped rows: row (the line number in the file) and error

  • columns (object): value, label and attributes: the columns read

  • inserted (number): Without dryRun: entries added (and updated: entries replaced)

DELETE https://api.apitraffic.io/v1/accounts/{accountSid}/dimensions/{key}/values/{value}

Remove one value’s entry. URL-encode the value. This removes the label and attributes, not the traffic.

Dropped tags

GET https://api.apitraffic.io/v1/accounts/{accountSid}/dimensionDiagnostics

Tags dropped over the last days, by reason.

  • days (query, number): Default 7, at most 90

Response

  • total (number): Tags dropped in the window

  • byReason (array): reason, count and up to 10 sampleKeys. Reasons: key_invalid, key_too_long, reserved_prefix, value_not_scalar, over_limit (more than 32 keys on a request), unregistered (past the registry limit; stored and searchable) and sdk (refused by an SDK before sending; no keys)

  • byDay (array): day, reason and count, newest day first

Activity events

Changes are recorded in the account’s activity log: data.dimension_updated, data.dimension_classified, data.dimension_promoted, data.dimension_demoted and data.catalog_changed.