Signal Schemas & Tags

A signal is the definition you ingest events against — its data type and tag schema together determine how values are validated, formatted, and aggregated. See Core Concepts for how signals fit into the wider organization/workspace hierarchy.

Data types

Every signal has exactly one data type, chosen when it's created:

• counter — things that happened, such as orders, signups or errors. Each event adds its value (often 1), so counters are usually summed.
• numeric — a measurement that can go up or down, such as queue depth, basket size or active sessions. Usually averaged.
• currency — a monetary amount, such as revenue or a refund. Usually summed.
• percentage — a ratio, displayed as a percentage.
• duration — an elapsed time, scaled and rounded by its configured durationUnit (ms, s, or min — defaults to ms).

Tag schemas

A signal can optionally define a tag schema: a fixed list of named, typed fields that every ingested event's tags object is validated against. Each entry has:

• key — the tag's name (1–100 characters, unique within the signal).
• type — string, number, or boolean.
• isRequired — whether ingestion is rejected if the tag is missing from the payload.
• description (optional) — what the tag means in your words, e.g. “assembly station, 1-12”. Shown with analysis findings.
• isIdentifier (optional) — “Exclude from analysis” in the app. For order, device or user IDs, which have too many values to compare.

A signal with no tag schema still accepts a free-form tags object — nothing is validated, since there's no schema to check it against.

A signal's direction says whether a rise is good news: higher_is_better, higher_is_worse or neutral (the default). It only changes how findings are worded, so refunds that rose “got worse” rather than “improved”.

Example

A signal keyed order_completed, data type currency, with a tag schema requiring currency (string) and allowing an optional customerTier (string):

{
  "signalKey": "order_completed",
  "value": 149.99,
  "tags": {
    "currency": "USD",
    "customerTier": "gold"
  }
}

Omitting the required currency tag, or sending a number where a string tag is expected, is rejected with a 400 Bad Request at ingestion time — see Ingestion API for the full error model.

Managing signals

Signals are created and edited from a workspace's Signals page. A signal that has never received data can be deleted outright; one with existing telemetry must be deactivated first (hidden from new ingestion, history preserved) before it can be purged.