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.
• 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 acquires a 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, 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.

• 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, 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.

• 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 snakecase except for the industry-standard gt/gte/lt/lte/in. Every negation has a `notprefix. String operators compare case-insensitively (equals:GetmatchesGET`); numeric, date, and existence operators are unaffected.

Per-type allowlist (UI filter components)

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.

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

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).

• 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). 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). 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). 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).

• 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).

• orange: Default.
• azure
• burgundy
• ink
• emerald
• violet

Appearance Scales

The UI scale (density) for a user’s app appearance (appearance_scale). 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.