Pages

Page Model

Fields

Field

Type

Description
object
"page"
id
string Unique identifier, prefixed with pag_.
team_id
string
project_id
string
name
string
created_at
updated_at
is_public
boolean Whether the page is reachable by anyone holding its URL.
public_url
string Where the page is served once published. The address resolves only while is_public is true.
slug
string The random segment of the public URL. Changes whenever the URL is refreshed.
access_code
string | null Code a visitor must enter to view the public page; null when none is set.
components
[] The components displayed on the page, in the order they appear.
time_range
Window every chart on the page covers.
custom_range_start_at
| null Start of the window, when the time range is custom.
custom_range_end_at
| null End of the window, when the time range is custom.
interval
Bucket size the charts use.
public_ui_show_alerts
boolean Whether alert markers are drawn on the charts of the public page.
public_ui_show_trends
boolean Whether trend lines enabled on each metric are shown publicly. Defaults to true.
public_ui_show_forecast
boolean Whether forecasts enabled on each metric are shown publicly. Defaults to true.
domain_routes
[] The custom domains this page is published on.

Page Domain Route Model

Fields

Field

Type

Description
object
"page_domain_route"
id
string Unique identifier, prefixed with pdr_.
domain_id
string
page_id
string
domain
string The domain name itself.
pathname
string Path the page is served at on that domain, leading slash included. / is the domain root.
public_url
string The full address the page is reachable at.
created_at
updated_at

List Pages

Endpoint

List a project's pages.

pages:read
GET
/v1/projects/:project_id/pages

Path Parameters

Field

Type

Description
project_id
string Unique identifier of the project.

Query Parameters

Field

Type

Description
order_by
string Field the results are sorted by. Defaults to "created_at". Accepted values: "created_at".
team_id
string Return only pages in this team.
project_id
string Return only pages in this project.
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

  • after and before are mutually exclusive.

Response

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

Retrieve Page

Endpoint

Retrieve a single page.

pages:read
GET
/v1/projects/:project_id/pages/:page_id

Path Parameters

Field

Type

Description
project_id
string Unique identifier of the project.
page_id
string Unique identifier of the page.

Comments

  • Includes every component on the page and the custom domains it is published to.

Response

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

Create Page

Endpoint

Create a page that displays a set of metrics.

pages:write
POST
/v1/projects/:project_id/pages

Path Parameters

Field

Type

Description
project_id
string Unique identifier of the project.

Request Body

Field

Type

Requirement

Description
name
string
Required
Display name for the page. Minimum length: 1. Maximum length: 64.
is_public
boolean
Optional
Whether the page is reachable by anyone holding its URL.
public_ui_show_alerts
boolean
Optional
Whether alert markers are drawn on the charts of the public page.
public_ui_show_trends
boolean
Optional
Whether trend lines enabled on each metric are shown on the public page. Defaults to true.
public_ui_show_forecast
boolean
Optional
Whether forecasts enabled on each metric are shown on the public page. Defaults to true.
access_code
string | null
Optional
Code a visitor must enter to view the public page. Send null for no code.
time_range
Optional
Window every chart on the page covers.
interval
Optional
Bucket size the charts use. Set to auto to pick one from the time range.
custom_range_start_at
Optional
Start of the window, when the time range is custom.
custom_range_end_at
Optional
End of the window, when the time range is custom.

Comments

  • A page is private until is_public is set. Publishing one generates the slug that forms its public URL.
  • A custom time range requires both custom_range_start_at and custom_range_end_at, at least 30 minutes apart, with the start before the end.
  • An access_code is trimmed, and an empty one is stored as no code at all.

Response

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

Update Page

Endpoint

Change a page's name, time range, or public access.

pages:write
POST
/v1/projects/:project_id/pages/:page_id

Path Parameters

Field

Type

Description
project_id
string Unique identifier of the project.
page_id
string Unique identifier of the page.

Request Body

Field

Type

Requirement

Description
name
string
Optional
Display name for the page. Minimum length: 1. Maximum length: 64.
is_public
boolean
Optional
Whether the page is reachable by anyone holding its URL.
public_ui_show_alerts
boolean
Optional
Whether alert markers are drawn on the charts of the public page.
public_ui_show_trends
boolean
Optional
Whether trend lines enabled on each metric are shown on the public page. Defaults to true.
public_ui_show_forecast
boolean
Optional
Whether forecasts enabled on each metric are shown on the public page. Defaults to true.
access_code
string | null
Optional
Code a visitor must enter to view the public page. Send null for no code.
time_range
Optional
Window every chart on the page covers.
interval
Optional
Bucket size the charts use. Set to auto to pick one from the time range.
custom_range_start_at
Optional
Start of the window, when the time range is custom.
custom_range_end_at
Optional
End of the window, when the time range is custom.

Comments

  • Send only the fields you are changing. Anything omitted keeps its current value.
  • Making a page private clears its public URL. Making it public again issues a new slug, so any previously shared link stops working.
  • A custom time range requires both custom_range_start_at and custom_range_end_at, at least 30 minutes apart, with the start before the end. The rule is checked against the page as it will be after the update, not against the fields you send.
  • An access_code is trimmed, and an empty one clears the code.

Response

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

Add Page Domain

Endpoint

Publish a page on one of your verified domains.

pages:write
domains:read
POST
/v1/projects/:project_id/pages/:page_id/domains/:domain_id

Path Parameters

Field

Type

Description
project_id
string Unique identifier of the project.
page_id
string Unique identifier of the page.
domain_id
string Unique identifier of the domain.

Request Body

Field

Type

Requirement

Description
pathname
string
Required
Path this page is served from on one custom Page domain. / serves the root.

Comments

  • The domain has to be verified before a page can be served on it.
  • Sending this again for the same domain moves the page to the new pathname rather than creating a second route.
  • Send / to serve the page at the domain root.
  • pathname is trimmed, lowercased, given a leading slash and stripped of any trailing slash before it is stored, so Status, /status and status/ all resolve to the same path rather than becoming separate routes.
  • pathname is either /, which serves the domain root, or a single segment of lowercase letters, numbers and single hyphens. Nested paths such as /team/status are rejected.
  • A small set of paths is reserved by Tailglow Pages and cannot be used.
  • Only one page can hold a given path on a domain, including /.
  • A stored pathname is at most 64 characters. The limit is applied after normalization, so the leading slash counts toward it even when you leave it off, while surrounding whitespace and a trailing slash do not.
  • A pathname longer than 256 characters is rejected before any of that, counting whatever you send including whitespace.
  • An empty or blank pathname is rejected. Delete the route to stop serving the page on a domain.

Response 201

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

Response 200

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

Remove Page Domain

Endpoint

Stop serving a page on one of your domains.

pages:write
domains:read
DELETE
/v1/projects/:project_id/pages/:page_id/domains/:domain_id

Path Parameters

Field

Type

Description
project_id
string Unique identifier of the project.
page_id
string Unique identifier of the page.
domain_id
string Unique identifier of the domain.

Comments

  • The page stays reachable on its Tailglow URL if it is still public.

Response

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

Refresh Page URL

Endpoint

Issue a new public URL for a page.

pages:write
POST
/v1/projects/:project_id/pages/:page_id/refresh

Path Parameters

Field

Type

Description
project_id
string Unique identifier of the project.
page_id
string Unique identifier of the page.

Comments

  • Use this when a shared link should stop working. The old URL returns a 404 immediately.

Response

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

Delete Page

Endpoint

Delete a page.

pages:delete
DELETE
/v1/projects/:project_id/pages/:page_id

Path Parameters

Field

Type

Description
project_id
string Unique identifier of the project.
page_id
string Unique identifier of the page.

Comments

  • The metrics the page displayed are not affected.

Response

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

Referenced Types

ISODateString

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

ComponentCardSize

1/1
1/2

MetricStatus

initializing
waiting_for_transforms
backfilling
active
error
cancelled

NullHandling

skip
count_as_zero

EmptyBucketHandling

zero
gaps

BackfillStrategy

newest_first
oldest_first

ChartFamily

cartesian
radial
geographic
temporal
hierarchical

ChartType

line
area
bar
pie
scatter
radar
stat
gauge
calendar
uptime

ChartColorMode

by_series
by_intensity
by_value

ChartColor

blue
red
amber
green
teal
purple
pink

ChartCurve

linear
step
smooth

ForecastHorizon

next_7_days
next_30_days
next_90_days
end_of_quarter
end_of_year
next_year

How far past now a chart projects its forecast. Values are relative to the moment the chart is viewed, so a saved horizon keeps projecting the same distance ahead as time passes rather than expiring on a fixed date. end_of_quarter and end_of_year run to the end of the calendar period that contains today, in UTC.

ForecastModel

auto
linear
exponential
logarithmic
logistic
sinusoidal

The curve a forecast is fitted with. auto follows the best-fitting model for the series, which is recalculated as data arrives and can therefore change between views; naming a model pins the projection to that curve.

MetricChartValue

count
average
sum
min
max
last
cumulative_sum
cumulative_count
p50
p95
p99
count_unique

Aggregation applied to a metric's values. Use last when records are snapshots of a persistent thing such as a deal, user, or inventory item: each time bucket contains the latest reading for that series in the bucket. Within the requested range, the last observed value carries forward across complete empty intervals instead of reading them as zero.

AnalyticsTimeRange

last_hour
last_6_hours
today
last_24_hours
yesterday
this_week
last_week
this_month
last_month
this_quarter
last_quarter
this_year
last_year
last_7_days
last_30_days
last_90_days
last_365_days
all_time
custom
next_7_days
next_30_days
next_90_days

The window a chart reads. Stored as a plain string rather than a database enum: the set is presentation, not something any query filters on, and the forward ranges in particular are expected to change as we learn what people forecast over. A next_* range ends after now, which is what turns a fitted trend into a visible forecast. The measured half of such a range is still measured; only the part past now is projected.

ChartInterval

minute
hour
day
month
auto

The Data Interval setting (Metric.ui_chart_interval and the aggregation interval query param). "auto" means the server picks the finest-safe tier for the current view, so brush-zoom naturally drills into a finer bucket. The RESOLVED tier returned by aggregation is always a plain DataInterval.