Projects

Project Model

Fields

Field

Type

Description
object
"project"
id
string Project identifier prefixed with prj_.
team_id
string
team_name
string
trial_expires_at
| null This team's trial lifecycle window; promotional units are shared across its projects.
name
string
start_at
Metrics collection begins at this time.
created_at
updated_at
deleted_at
| null Scheduled deletion time; null when deletion is not scheduled.
last_activity_at
| null Most recent authenticated ingest time; null if none has occurred.
late_data_window_minutes
number How many minutes behind the completeness watermark an event with an overridden timestamp may arrive and still be included automatically. Later data is recorded and surfaced for manual re-backfill. 0 means the watermark is final as it advances. Data sent live is never affected.
server_endpoint
string | null Project-specific ingest endpoint; null while unavailable.
queued_server_count
number | null Server count a scale request asked for that is waiting to be applied, because a platform update is in progress or the project has not finished updating to the current platform version. null when nothing is queued.
storage_gb
number Stored data for this project, in gigabytes of uncompressed data: raw ingested files and artifacts, plus view output and minute-level rollups. Recalculated hourly; billing_updated_at is the last refresh.
billing_period_server_months
number Server-months this project's servers have accrued in the current calendar-month billing period, counted up to the last refresh.
billing_updated_at
| null Last billing-cache refresh; null before the first calculation.

Late Data Model

Fields

Field

Type

Description
object
"late_data_file"
id
string Unique identifier, prefixed with ldf_.
view_id
string
view_name
string Display name of the view whose data carried the late events.
excluded_count
number How many events were kept out of charts because their timestamps fell behind the project's late data window. The events themselves are stored; only their aggregation waits.
min_event_at
The earliest event time among the excluded events. A re-backfill folds back to this instant.
max_event_at
The latest event time among the excluded events.
exclusion_below
The boundary the events fell behind. Events at or after it were included normally.
refold_queued_at
| null When a re-backfill was requested for these events; null until requested.
refolded_at
| null When the re-backfill finished folding the events into charts; null until complete.
created_at

Live Pipeline Model

Fields

Field

Type

Description
object
"project_pipeline_live"
observed_at
pending_records
number | null Valid spooled records awaiting write, including processing. Null when the queue is unknown.
processing_records
number | null Pending records currently being processed.
pending_observed_at
| null Oldest contributing queue observation, independent of the server heartbeat.
pending_is_estimated
boolean The queue changed during inspection; available counts are estimates from durable records.
state
"fresh" | "stale" | "unavailable" Queue freshness across all current project servers, including deployment surges.
contributing_servers
number
fresh_servers
number
window_start_at
Inclusive start of the last completed minute.
window_end_at
Exclusive end of the last completed minute.
throughput_records
number | null Records processed in the completed minute. Null when any contributor lacks telemetry.
errors
number | null Rejected requests and dropped frames in the completed minute, not a record count.
pipeline_error_counts
Partial | null Map from each PipelineErrorReason key to its error count for the completed minute. Omitted keys had no errors; null means telemetry is incomplete.

Usage Sample Model

Fields

Field

Type

Description
object
"usage_sample"
sampled_at
When the reading was taken. Readings are hourly, on the hour. With interval=day this is the timestamp of the day's last reading, not midnight.
collection_gb
number Gigabytes of raw event data held in the project's collections, measured uncompressed, exactly as it is billed.
artifact_gb
number Gigabytes of artifacts extracted from the project's events, measured uncompressed.
view_gb
number Gigabytes of view records the project's views produced, measured uncompressed.
rollup_gb
number Gigabytes of rollup data behind the project's charts, measured uncompressed. Counts the minute tier only, matching what invoices charge for.
total_gb
number The four components added together: everything the project stored at this reading.

Attention Item Model

Fields

Field

Type

Description
object
"attention_item"
type
tier
resource_id
string | null The resource to open to act on the condition: the metric behind a firing monitor, the view behind a failing transform, otherwise the check, view, metric, drain, pull or server itself. Null when the item covers the project as a whole, which is the case for refused requests.
resource_name
string | null The name shown for the condition, which can belong to a related resource: a firing monitor's item names the monitor while resource_id opens its metric. Null whenever resource_id is null.
count
number | null How much of the condition there is, in the unit that fits it: requests refused (not records) over the last 24 hours, or the last hour for capacity, series a monitor is firing on, a view's failing transforms, events waiting on a shape change, consecutive failures of a check, pull, or drain, or a hot server's average load in percent. Null when the condition has no quantity.
since
| null When the condition started, as accurately as Tailglow knows. Null when nothing on record marks a beginning: a check that has never once succeeded, or a server under sustained load, which is judged from an average rather than a start.
ended_at
| null When the condition stopped, for a resolved item: to the minute within the last hour, to the end of the hour before that. Null while the condition is still true, including while a server that was refusing has not reported since.
detail
string | null A short machine-readable qualifier that narrows the type: the refusal reason group, the firing monitor's id, or cpu or mem for the load that made a server hot. A stable identifier meant for branching in code, never a sentence to display. Null when the type needs no qualifier.

List Projects

Endpoint

Retrieve a list of projects for the current team.

projects:read
GET
/v1/projects

Query Parameters

Field

Type

Description
order_by
string Field used to order the projects. Defaults to "name". Accepted values: "created_at","name".
limit
number Maximum number of items to return. Defaults to 25. Minimum: 1. Maximum: 200.
after
string Cursor from pagination.next_cursor of a previous response. Returns the resources after that page.
before
string Cursor from pagination.prev_cursor of a previous response. Returns the resources before that page.
sort
string Sort direction for the result set. Defaults to "desc". Accepted values: "asc","desc".

Comments

  • When neither sort nor order_by is provided, the route defaults sort to "asc".
  • after and before are mutually exclusive.

Response

200 
{
  message: string;
  data: Project[];
  status: 200;
  error: null;
  pagination: Pagination;
  endpoint: string;
}

Retrieve Project

Endpoint

Retrieve a single project.

projects:read
GET
/v1/projects/:project_id

Path Parameters

Field

Type

Description
project_id
string Unique identifier of the project.

Response

200 
{
  message: string;
  data: Project;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

Retrieve Project Pipeline

Endpoint

Retrieve ingest activity across all of a project's servers.

servers:read
GET
/v1/projects/:project_id/pipeline

Path Parameters

Field

Type

Description
project_id
string Unique identifier of the project.

Query Parameters

Field

Type

Description
start_at
Start time (ISO format, default: 12 hours ago).
end_at
End time (ISO format, default: now).
interval
string Aggregation interval. Defaults to "minute". Accepted values: "minute","hour".

Comments

  • Includes temporary deployment servers and their archived history. Pending averages valid queued records; throughput counts drained records. Older pending history without record counts is unknown.

Response

200 
{
  message: string;
  data: TimeseriesAggregation;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

Retrieve Live Project Pipeline

Endpoint

Retrieve the current project queue and ingest totals for the last completed minute.

servers:read
GET
/v1/projects/:project_id/pipeline/live

Path Parameters

Field

Type

Description
project_id
string Unique identifier of the project.

Comments

  • Includes temporary deployment servers. Queue freshness is independent of heartbeat freshness. Observations taken while queues change return estimated counts from durable records; unreadable observations or unknown write outcomes return null counts.
  • Throughput and error totals cover the last completed minute. Errors count requests or frames, and totals are null when telemetry is incomplete.

Response

200 
{
  message: string;
  data: ProjectPipelineLive;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

Create Project

Endpoint

Create a new project for the current team.

projects:write
POST
/v1/projects

Request Body

Field

Type

Requirement

Description
name
string
Required
Display name for the project. Minimum length: 1. Maximum length: 60.
start_at
Optional
Date and time when the project began collecting data.

Response

201 
{
  message: string;
  data: Project;
  status: 201;
  error: null;
  pagination: null;
  endpoint: string;
}

Update Project

Endpoint

Update an existing project.

projects:write
POST
/v1/projects/:project_id

Path Parameters

Field

Type

Description
project_id
string Unique identifier of the project.

Request Body

Field

Type

Requirement

Description
name
string
Optional
Display name for the project. Minimum length: 1. Maximum length: 60.
start_at
Optional
Date and time when the project began collecting data.
late_data_window_minutes
integer
Optional
How many minutes behind the completeness watermark an event with an overridden timestamp may arrive and still be included automatically. Later data is recorded and surfaced for manual re-backfill instead of being included. 0 means the watermark is final as it advances. Only events with overridden timestamps can be late; data sent live is never affected. Maximum 129600 (90 days). Minimum: 0. Maximum: 129600.
deleted_at
null
Optional
Set to null to cancel a scheduled project deletion.

Response

200 
{
  message: string;
  data: Project;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

Delete Project

Endpoint

Schedule a project for deletion.

projects:delete
DELETE
/v1/projects/:project_id

Path Parameters

Field

Type

Description
project_id
string Unique identifier of the project.

Comments

  • The project is hidden immediately and permanently removed 7 days later. Restore it before then by updating it with deleted_at set to null.

Response

200 
{
  message: string;
  data: Project;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

Force Delete Project

Endpoint

Delete a project permanently, without waiting out its restore window.

projects:delete
DELETE
/v1/projects/:project_id/force

Path Parameters

Field

Type

Description
project_id
string Unique identifier of the project.

Comments

  • Works on a live project as well as one already scheduled for deletion.
  • Every source, collection, view, metric and record in the project is destroyed immediately, and its servers are torn down. Nothing here can be restored.

Response

200 
{
  message: string;
  data: null;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

List Late Data

Endpoint

Retrieve the events held out of charts by the project's late data window, grouped per data file.

projects:read
GET
/v1/projects/:project_id/late_data

Path Parameters

Field

Type

Description
project_id
string Unique identifier of the project.

Query Parameters

Field

Type

Description
order_by
string Field used to order the late data records. Defaults to "created_at". Accepted values: "created_at","min_event_at".
refolded
string Filter by re-backfill state: false returns records whose events are still excluded from charts, true returns records a completed re-backfill has folded in. Accepted values: "true","false".
limit
number Maximum number of items to return. Defaults to 25. Minimum: 1. Maximum: 200.
after
string Cursor from pagination.next_cursor of a previous response. Returns the resources after that page.
before
string Cursor from pagination.prev_cursor of a previous response. Returns the resources before that page.
sort
string Sort direction for the result set. Defaults to "desc". Accepted values: "asc","desc".

Comments

  • Events with overridden timestamps beyond the late data window are stored and counted here instead of entering charts. Data sent live is never held.
  • Records with refolded_at set have already been folded into charts by a completed re-backfill; filter with refolded=false for records still waiting.
  • after and before are mutually exclusive.

Response

200 
{
  message: string;
  data: LateDataFile[];
  status: 200;
  error: null;
  pagination: Pagination;
  endpoint: string;
}

Re-backfill Late Data

Endpoint

Start a re-backfill that folds one late data record's events into charts.

projects:write
POST
/v1/projects/:project_id/late_data/:late_data_file_id/re_backfill

Path Parameters

Field

Type

Description
project_id
string Unique identifier of the project.
late_data_file_id
string Unique identifier of the late data.

Comments

  • Idempotent: requesting a re-backfill that is already queued or complete returns the record unchanged.
  • The fold is bounded to the excluded events, so data already in charts is never counted twice. refolded_at is set once the fold's durable receipts land.

Response

200 
{
  message: string;
  data: LateDataFile;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

Retrieve Project Usage

Endpoint

Retrieve how much the project stored over a time range.

projects:read
GET
/v1/projects/:project_id/usage

Path Parameters

Field

Type

Description
project_id
string Unique identifier of the project.

Query Parameters

Field

Type

Requirement

Description
start_at
Required
Start of the range, inclusive (ISO format).
end_at
Optional
End of the range, inclusive (ISO format, default: now).
interval
string
Optional
Reading cadence returned: every hourly reading, or one reading per UTC day. Defaults to "hour". Accepted values: "hour","day".

Comments

  • Readings are taken hourly and are the same measurements the project is billed on. Gigabytes are logical (uncompressed) bytes.
  • interval=day returns the last reading of each UTC day rather than an average, so a row is what the project held when the day closed. Its sampled_at is that reading's own hour.
  • Readings start when Tailglow began recording them, so a range reaching further back returns nothing for the hours before that.
  • start_at must be earlier than end_at, and the range cannot be longer than 400 days.

Response

200 
{
  message: string;
  data: UsageSample[];
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

Retrieve Project Attention

Endpoint

Retrieve everything in the project that is asking for a human right now.

projects:read
GET
/v1/projects/:project_id/attention

Path Parameters

Field

Type

Description
project_id
string Unique identifier of the project.

Comments

  • An item appears only when Tailglow entered a state on its own. Anything a project chose, such as a paused pull, a paused drain, or a paused monitor, is never reported here.
  • tier orders the list. losing_data means requests are being refused right now, within the last 5 minutes: for a reason a retry cannot fix, or for capacity after at least 5 minutes of unbroken refusals. firing means a monitor or check the project set up is currently triggered, or a server has run under sustained heavy load. stalled means a pipeline stopped making progress and its data is going stale. suspended means Tailglow switched something off and it stays off until it is fixed. resolved means refusals that lost data have stopped; ended_at says when.
  • Items disappear the moment their condition clears, with one exception so a loss is not missed: refusals that stop stay as resolved, for up to 24 hours for a key or payload refusal and up to an hour for capacity. A refusal item's count covers that whole window, not only the current spell. Refusals only count as stopped once every running server that was refusing has reported since; until then the item stays losing_data. Readings from the project's servers are cached briefly, so a condition that just started can take up to a minute to appear.
  • Items cover only resources the caller's key or role can read: without a resource's read permission, its conditions are left out. Refusal and server load items need servers:read, and firing monitors need alerts:read.
  • Items are already ranked, most urgent first. One item covers each firing monitor, and each view's failing transforms, joins, or shape waits. The response is capped per condition so a project in a bad state returns a readable list rather than every affected resource.

Response

200 
{
  message: string;
  data: AttentionItem[];
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

Referenced Types

ISODateString

An ISO 8601 date-time string returned at the JSON API boundary.

PipelineErrorReason

auth_missing_credentials
auth_invalid_credentials
payload_too_large
request_validation_failed
server_error
spool_full_disk_gate
spool_full_storage_write
spool_full_ingest_queue
spool_full_wal_unavailable
frame_invalid
empty_payload
source_deleted
connection_closed
auth_unavailable

AttentionItemType

ingest_refusals
capacity_refusals
monitor_firing
check_down
transform_error
metric_error
join_error
shape_deferral
pull_suspended
drain_suspended
drain_unverified
servers_hot

The condition an attention item reports. Every value is a state Tailglow entered on its own, so nothing a project deliberately turned off is ever reported here.

AttentionTier

losing_data
firing
stalled
suspended
resolved

How urgent an attention item is, most urgent first. losing_data means requests are being refused right now in a way that loses data unless the sender acts, or were until a server that was refusing stopped reporting. firing means something the project asked to be told about is currently true, or a server has run under sustained heavy load. stalled means a pipeline stopped making progress and existing data is going stale. suspended means Tailglow switched something off and it stays off until it is fixed. resolved means refusals that lost data have stopped; the item stays for a while so the loss is still visible, and says when it ended.