# Enums

This page lists common enum values used across the API.

## Metric Group By

The `group_by` field accepts any string field names from your view's output schema. There is no fixed set of allowed values.

## Chart Types

- `line`
- `area`
- `bar`
- `pie`
- `scatter`
- `radar`
- `stat`
- `gauge`
- `calendar`
- `uptime`

## Chart Color Modes

How a chart picks colors. The chart type must allow the chosen mode (e.g., gauge supports `by_series` and `by_value`; calendar supports `by_series` and `by_intensity`).

- `by_series`: Each series gets its own color. Colors are auto-assigned from a deterministic series-hash → palette projection (stable across drill-down). Per-series overrides via [Update Series](/api/metrics#update-series).
- `by_intensity`: One base color (`ui_chart_color_base`); the renderer modulates lightness/opacity by value. Used by calendar / heatmap-style charts.
- `by_value`: Ordered rules (`ui_chart_color_rules`) map each value to a color. First matching rule wins; no match falls back to system default. Used by gauges and uptime strips.

## Metric Chart Values

Determines which aggregation is displayed by default on a chart.

- `count`: Number of records.
- `average`: Average of the record `value` field.
- `sum`: Sum of the record `value` field.
- `min`: Minimum of the record `value` field.
- `max`: Maximum of the record `value` field.
- `last`: Latest reading in each time bucket per group_by combination. Within the requested range, the last observed value carries forward across complete empty intervals. Use for entity/snapshot data (e.g., deals, users, inventory).
- `cumulative_sum`: Cumulative sum of the record `value` field over the time range.
- `cumulative_count`: Cumulative count of records over the time range.
- `p50`: 50th percentile (median) of the record `value` field.
- `p95`: 95th percentile of the record `value` field.
- `p99`: 99th percentile of the record `value` field.
- `count_unique`: Number of distinct values of the `unique_field`. Exact for small cardinalities (up to 8,192), approximate for larger sets.

## Empty Bucket Handling

Controls how time intervals with no data render on a metric's chart. This is a display setting: changing it applies instantly to all historical data with no recalculation.

- `zero`: Empty intervals render as a true 0. The right choice for additive aggregations (`count`, `sum`, `cumulative_*`, `count_unique`) where "nothing happened" means zero. Monitors evaluate an empty window as 0, so conditions like `count == 0` can trigger.
- `gaps`: Empty intervals render as gaps (`null` values in `series.records`) and are excluded from trend line fitting. The right choice for observational aggregations (`average`, `min`, `max`, percentiles) where an empty interval has no defined value. Monitors skip evaluation when a series has no data in the window: nothing fires and open alerts stay open until data returns. The `last` chart value is the one exception on charts: it carries the latest measured value forward through empty intervals in both modes.

New metrics default based on their `ui_chart_value`: additive aggregations get `zero`, observational aggregations get `gaps`.

## Chart Colors

Possible values for the `color` property within `ui_chart_colors`.

- `blue`
- `red`
- `amber`
- `green`
- `teal`
- `purple`
- `pink`

## Analytics Time Ranges

Used for `time_range` (in aggregation requests) and `ui_chart_time_range` (in the metric object).

- `last_hour`
- `last_6_hours`
- `today`
- `last_24_hours`
- `yesterday`
- `this_week`
- `last_7_days`
- `last_week`
- `this_month`
- `last_30_days`
- `last_month`
- `this_quarter`
- `last_90_days`
- `last_quarter`
- `this_year`
- `last_365_days`
- `last_year`
- `all_time`
- `custom` (Requires specific start/end dates)
- `next_7_days`
- `next_30_days`
- `next_90_days`

A `next_*` range reaches the same distance into the past as it does into the future, so a chart has history to fit a forecast from.

## Forecast Horizons

Used for `ui_chart_forecast_horizon` (in the metric object). Relative values resolve when the chart is viewed.

- `next_7_days`
- `next_30_days`
- `next_90_days`
- `end_of_quarter`
- `end_of_year`
- `next_year`

## Forecast Models

Used for `ui_chart_forecast_model` (in the metric object). `auto` follows whichever model fits the data best.

- `auto`
- `linear`
- `exponential`
- `logarithmic`
- `logistic`
- `sinusoidal`

## Metric Data Intervals

Used for `interval` (in aggregation requests) and `ui_chart_interval` (in the metric object).

- `minute`
- `hour`
- `day`
- `month`

## View Transform Modes

How a [View](/api/views#model) acquires a [TGL](/guides/tgl) transform for schema versions discovered after it was created.

Both modes first try to reuse one of the view's existing scripts. Reuse requires a typed candidate signature and at least one of the script's read paths to be present. A present path whose value is null counts as evidence; an absent path does not. An unknown-only signature is not eligible for reuse. The modes differ only when no existing script can read the new shape:

- `auto`: Tailglow generates a script for the new version.
- `manual`: The version waits for you to supply a compatible script instead of generating one automatically. A supplied script can wait for input before validation.

## View Transform Conflict Resolutions

Controls what happens when editing a collection-backed transform would make the new script incompatible with some schema versions that used the prior script.

- `strand`: Default. Compatible versions adopt the edit; conflicting versions move to queued placeholders so they can receive their own script.
- `keep`: Compatible versions adopt the edit; conflicting versions remain on the prior script.

## Schema Version States

The lifecycle of a collection's [schema version](/guides/concepts#schema-versions), from first sight to trust.

- `candidate`: The shape has been seen once. Its records are stored and served immediately by any view mapping that already fits them, but no mapping is written for it yet.
- `settled`: The shape was seen again after the collection's recurrence gap, arrived in one batch with at least the bulk row count, or a person settled it. Only settled versions are offered to views for authoring, and a settled version never goes back.
- `stale`: A candidate that was not seen again within the stale window. Its rows stay stored but unclassified. A stale shape that returns settles.

## Schema Settlements

What settled a schema version.

- `recurrence`: The shape was seen again after the collection's recurrence gap.
- `bulk`: One batch carried at least the collection's bulk row count of the shape.
- `person`: Someone settled the version from the collection page or through the API.

## Schema Rule Modes

How a collection applies each of its three identity rules: nulls and absent values, optional keys, and the detector. See [Schema settings](/guides/sources#schema-settings).

- `auto`: Tailglow decides. Null and absent values are accepted at any path a mapping reads, a record whose keys are a subset of a version's keys joins that version, and a safe opaque-path proposal from the detector is applied on its own.
- `manual`: A person decides at each of those points.

## Metric Statuses

The current status of the metric.

- `initializing`: Metric is being created.
- `waiting_for_transforms`: Metric is waiting for its source transforms to finish processing.
- `backfilling`: Historical data is being backfilled (also covers re-backfill triggered by data-feed changes).
- `active`: Metric is up-to-date and collecting new data.
- `error`: An error occurred during processing.
- `cancelled`: The metric, or the view it reads, was deleted while a backfill was still running, so the backfill was cancelled instead of being allowed to finish. Restoring the metric within its 24-hour window leaves it here; re-run the backfill to finish what it missed.

## View Statuses

The current status of a [View](/api/views#model), derived from its transforms.

- `empty`: The view has no transforms yet.
- `building`: A transform is waiting for input or processing data, including indexing history.
- `needs_transform`: A transform script needs to be written or corrected. This can occur in either transform mode.
- `active`: At least one transform is finished and serving data.
- `cancelled`: The view was deleted while it was still indexing, so the indexing was cancelled rather than allowed to finish. Deleted views remain readable until permanent removal 24 hours later, and they report this status for that window.
- `error`: A transform failed to compile, or its indexing failed.

## Metric Values

Indicates which aggregations were calculated in the [Metric Aggregation Model](/api/metrics#aggregation-model).

- `count`
- `sum`
- `min`
- `max`

## Filter Operators

The canonical operator vocabulary used everywhere filters appear: list endpoint query parameters (`?<field>=<op>:<value>`), metric `filters` (applied at rollup time), facet record queries against indexed views, and the UI filter components.

URL syntax is flat: `?type_1=equals:Fire&limit=50`. Operator names are long-form snake*case except for the industry-standard `gt`/`gte`/`lt`/`lte`/`in`. Every negation has a `not*` prefix. String operators compare case-insensitively (`equals:Get`matches`GET`); numeric, date, and existence operators are unaffected.

| Operator          | Semantics                                     |
| ----------------- | --------------------------------------------- |
| `equals`          | Exact match                                   |
| `not_equals`      | Inverse of `equals`                           |
| `gt` / `gte`      | Greater than (strict / inclusive)             |
| `lt` / `lte`      | Less than (strict / inclusive)                |
| `between`         | Inclusive range; value is `min,max`           |
| `contains`        | Substring match (strings)                     |
| `not_contains`    | Inverse of `contains`                         |
| `starts_with`     | Prefix match (strings)                        |
| `not_starts_with` | Inverse of `starts_with`                      |
| `ends_with`       | Suffix match (strings)                        |
| `not_ends_with`   | Inverse of `ends_with`                        |
| `in`              | Scalar field, value in a comma-separated list |
| `not_in`          | Inverse of `in`                               |
| `has`             | Array field contains the given scalar         |
| `not_has`         | Inverse of `has`                              |
| `has_any`         | Array field intersects a comma-separated list |
| `exists`          | Field has a non-null value                    |
| `not_exists`      | Field is null or absent                       |

### Per-type allowlist (UI filter components)

| Field type | Allowed operators                                                                                                                  |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `string`   | `equals`, `not_equals`, `contains`, `not_contains`, `starts_with`, `not_starts_with`, `ends_with`, `not_ends_with`, `in`, `not_in` |
| `number`   | `equals`, `not_equals`, `gt`, `gte`, `lt`, `lte`, `between`, `in`, `not_in`                                                        |
| `date`     | `equals`, `not_equals`, `gt`, `gte`, `lt`, `lte`, `between`                                                                        |
| `array`    | `has`, `not_has`, `has_any`                                                                                                        |
| `boolean`  | `equals`, `not_equals`                                                                                                             |

### Surface availability

Not every operator is supported by every surface. The metric filter pipeline supports the full vocabulary; CRUD list endpoints reject existence operators in v1 (the per-field nullable-aware validators land separately); facet record queries are limited to the SQLite-indexed subset.

| Operator          | Metric filters | CRUD list | Facet records |
| ----------------- | :------------: | :-------: | :-----------: |
| `equals`          |       ✓        |     ✓     |       ✓       |
| `not_equals`      |       ✓        |     ✓     |               |
| `gt`              |       ✓        |     ✓     |               |
| `gte`             |       ✓        |     ✓     |       ✓       |
| `lt`              |       ✓        |     ✓     |               |
| `lte`             |       ✓        |     ✓     |       ✓       |
| `between`         |       ✓        |     ✓     |               |
| `contains`        |       ✓        |     ✓     |               |
| `not_contains`    |       ✓        |     ✓     |               |
| `starts_with`     |       ✓        |     ✓     |       ✓       |
| `not_starts_with` |       ✓        |     ✓     |               |
| `ends_with`       |       ✓        |     ✓     |               |
| `not_ends_with`   |       ✓        |     ✓     |               |
| `in` / `not_in`   |       ✓        |     ✓     |               |
| `has`             |       ✓        |           |               |
| `not_has`         |       ✓        |           |               |
| `has_any`         |       ✓        |           |               |
| `exists`          |       ✓        |           |               |
| `not_exists`      |       ✓        |           |               |

### Reserved query parameter keys

Several keys are reserved as query-string control parameters across every endpoint. View `output_schema` fields and facet `field_path` values cannot use any of these names:

`limit`, `cursor`, `page`, `sort`, `order_by`, `after`, `before`, `start_at`, `end_at`, `timezone`, `interval`, `search`

## Monitor Condition Types

| Value | Meaning |
| --- | --- |
| `threshold` | Compare the selected metric value with a threshold. |
| `sustained` | Require that comparison to hold for a duration. |
| `existence` | Fire when the selected value is greater than zero. |
| `absence` | Fire when a complete evaluation window contains no observations, even on a chart that displays gaps. Requires Count and a finite window. |

For absence, Total watches the whole filtered feed. Any series and Each series watch known individual series. A measured value of zero is still an observation. Unknown completeness postpones evaluation.

## Drain Statuses

Lifecycle status of a Drain.

- `draft`: Created but never verified. No outbound traffic.
- `pending_verification`: A verification marker has been sent to the destination and we're waiting for the customer to paste it back via Confirm Verification.
- `active`: Drain is verified, resumed, and forwarding records on the recurring schedule.
- `paused`: You stopped the drain, or it was freshly verified (verification intentionally lands paused so you can sample before going live). Only you start it again. Resume via Resume Drain.
- `disabled`: Tailglow stopped the drain after 72 hours of consecutive failures. Resume the same way after fixing the destination; resuming clears the failure counters.

## Drain Body Formats

Wire format for the body of outbound drain POSTs.

- `ndjson`: Newline-delimited JSON. Default. One record per line. Sent with `Content-Type: application/x-ndjson`.
- `json`: A single JSON array of records. Required by Datadog Logs and similar receivers. Sent with `Content-Type: application/json`.

## Drain Compressions

Wire compression for outbound drain POSTs.

- `none`: Default. Body is sent uncompressed and works with any receiver.
- `gzip`: Body is gzipped and `Content-Encoding: gzip` is added. Receivers MUST decompress `Content-Encoding` for this to work.

## Check Statuses

Lifecycle status of a Check ([`status`](/api/checks#model)).

- `active`: Running on its schedule.
- `paused`: You stopped the check. Nothing is recorded for the minutes a pause covers, so the uptime record shows a gap rather than downtime. Start it again with Resume Check.
- `disabled`: Tailglow stopped the check because the team is no longer in good standing. A failing endpoint never lands here, however long the failure lasts, because the outage is the thing the check exists to record. Resume the same way once the account is settled.

## Check Methods

The HTTP method a check uses to request its endpoint ([`method`](/api/checks#model)). Both are observational, so a check can never change anything at the endpoint it watches.

- `get`: Default.
- `post`: For health endpoints that only answer to POST. Only a `post` check may send a `request_body`.

## Check Error Stages

Which step of the most recent failed run went wrong ([`last_error_stage`](/api/checks#model)). A check never reads the response body, so there is no parse stage.

- `request`: No usable response arrived. The address was refused by the outbound guard, the request timed out, TLS failed, the connection was reset, or the body ran past the size cap before it finished.
- `response`: The endpoint answered, but not with a 2xx status.

## Appearance Palettes

The color palette for a user's app appearance ([`appearance_palette`](/api/users#model)). Sets the light or dark scheme.

- `light`
- `dark`
- `dim`: Default. A softer dark scheme.
- `midnight`
- `paper`

## Appearance Type Sets

The font pairing for a user's app appearance ([`appearance_type_set`](/api/users#model)).

- `system`: Default. The operating system's native font stack.
- `grotesk`
- `editorial`
- `geometric`

## Appearance Accents

The accent color for a user's app appearance ([`appearance_accent`](/api/users#model)).

- `orange`: Default.
- `azure`
- `burgundy`
- `ink`
- `emerald`
- `violet`

## Appearance Scales

The UI scale (density) for a user's app appearance ([`appearance_scale`](/api/users#model)). Applies at tablet and desktop widths; mobile always renders at full size.

- `comfortable`: 100% scale.
- `cozy`: 90% scale.
- `compact`: Default. 80% scale, fits more on screen.

## Ingest Pipeline Error Reasons

The reasons behind the Errors series on a server's Ingest Pipeline chart. Every reason is a refusal issued before acceptance: the sender received an error response and nothing was recorded from that request. Accepted data is never dropped. It is queued on the server and retried until it lands.

Reasons where retrying the same request delivers the data. Tailglow SDKs retry these automatically; if you send raw HTTP, retry on any 5xx response:

- `connection_closed`: The sender closed the connection before the upload finished.
- `server_error`: An unexpected error while handling the request.
- `spool_full_disk_gate`: The server paused intake to protect its disk from filling.
- `spool_full_storage_write`: A buffer write failed while accepting the request.
- `spool_full_ingest_queue`: The intake queue was momentarily full.
- `spool_full_wal_unavailable`: The write buffer was restarting.
- `auth_unavailable`: The ingest key could not be verified because the verification service was unreachable. The key itself was not rejected.

Reasons where the request itself must change. Retrying the same request is refused again:

- `auth_missing_credentials`: No ingest key was provided.
- `auth_invalid_credentials`: The ingest key is wrong or revoked.
- `payload_too_large`: The payload exceeds the size limit.
- `request_validation_failed`: The request body or parameters are invalid.
- `frame_invalid`: A frame in the payload could not be parsed.
- `empty_payload`: The request carried no data.
- `source_deleted`: The target source no longer exists.