Trackz Public API v1 Reference

Overview

The Trackz Public API lets you read your workspace data from your own scripts, dashboards, and CI pipelines instead of clicking through the app. You authenticate with an API token you create yourself in Settings, and every request is scoped to the workspace that owns the token.

Version 1 is read-only and covers two resources:

Projects — list the projects in your workspace.
Uptime — list your uptime monitors with their latest check, search them, and pull the check history for a single monitor.

Only GET requests are accepted. Creating, updating, and deleting still happen in the dashboard. Support for the remaining resources — SSL, Performance, SMTP, SEO, and API monitors — is planned for a later release.

Prerequisites

A Trackz workspace on a paid plan. The public API is not available on the Free plan, and the legacy Starter plan is treated the same way. Every other plan — Pro Starter, Pro, Pro Max, Business 250, Business 500, Business 1K, and Enterprise — includes it.
Owner access to the workspace. Only the workspace owner can create or revoke API tokens.
At least one project with an uptime-enabled website, if you want the uptime endpoints to return anything.

The plan is checked twice: once when you create a token, and again on every single API request. If a workspace downgrades to Free, its existing tokens stop working immediately — they are not deleted, but every call returns 402 until the workspace is on a paid plan again.

Creating an API token

In the Trackz dashboard, open Settings → API Tokens.
Click Create Token.
Give the token a Name that tells you where it is used — for example CI pipeline or Status page. The name is only a label; it has no effect on what the token can read.
Click Create Token to confirm.
The Copy your API token dialog appears with the full token. Click Copy, paste it into your secret store, then click Done.

The token is shown exactly once. Trackz stores only a SHA-256 hash of it, so nobody — including Trackz support — can retrieve it later. The token list shows just the first 12 characters and the last 4 so you can tell your tokens apart. If you lose a token, revoke it and create a new one.

Tokens look like trkz_ followed by 48 hexadecimal characters:

trkz_9f2c1ab47e0d3856b1fa04c7d29e5b83a6710fe4cc9d2b05

Treat a token like a password. Anyone holding it can read everything in your workspace. Keep it in an environment variable or a secrets manager, never in committed source code.

Version 1 tokens do not expire and cannot be scoped to individual resources. Every token can read every resource the API exposes.

Authentication

Send the token in the Authorization header as a Bearer credential:

Authorization: Bearer trkz_9f2c1ab47e0d3856b1fa04c7d29e5b83a6710fe4cc9d2b05

The base URL for every endpoint is:

https://api.usetrackz.app/api/public/v1

A minimal request:

curl https://api.usetrackz.app/api/public/v1/projects \
  -H "Authorization: Bearer $TRACKZ_TOKEN"

A request with no Authorization header, a header that is not a Bearer credential, a token that does not start with trkz_, an unrecognised token, or a revoked token all return 401. See Errors.

Pagination

GET /projects and GET /uptime are paginated with two query parameters:

Parameter	Type	Default	Max	Notes
`page`	integer	`1`	—	1-based. Values below `1` are treated as `1`.
`limit`	integer	`20`	`100`	Values above `100` are clamped to `100`.

Both return the same envelope:

{
  "data": [],
  "total": 0,
  "page": 1,
  "limit": 20
}

total is the number of records matching your filters across all pages, not the number in data. To walk every page, request page=1, page=2, and so on until you have collected total records.

GET /uptime/search returns the same four fields for consistency, but it is not pageable: it always reports page: 1 and limit: 20, and returns at most 20 matches. GET /uptime/{targetId} uses a different shape — see its section below.

Endpoints

GET /projects

Lists the projects in your workspace, newest first.

Parameter	Type	Default	Max	Allowed values
`page`	integer	`1`	—	Any integer ≥ 1
`limit`	integer	`20`	`100`	Any integer

curl "https://api.usetrackz.app/api/public/v1/projects?page=1&limit=20" \
  -H "Authorization: Bearer $TRACKZ_TOKEN"

{
  "data": [
    {
      "id": "clx8k2p9a0001qwer4t5y6u7i",
      "name": "Acme Storefront",
      "tags": ["ecommerce", "eu"],
      "status": "ACTIVE",
      "createdAt": "2026-04-21T09:14:03.221Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}

status is ACTIVE, or PAUSED when the project has been paused in the dashboard.

GET /uptime

Lists uptime-enabled monitored targets with their most recent check, newest first. Targets belonging to websites with uptime monitoring switched off are never returned.

Parameter	Type	Default	Max	Allowed values
`page`	integer	`1`	—	Any integer ≥ 1
`limit`	integer	`20`	`100`	Any integer
`projectId`	string	—	—	A project id from `GET /projects`
`environmentId`	string	—	—	An environment id
`status`	string	—	—	`up` or `down`

status=up returns targets whose website is HEALTHY. status=down returns targets whose website is CRITICAL or WARNING. Any other value returns 400. Filters combine — passing projectId, environmentId, and status together narrows on all three.

curl "https://api.usetrackz.app/api/public/v1/uptime?status=down&limit=50" \
  -H "Authorization: Bearer $TRACKZ_TOKEN"

{
  "data": [
    {
      "id": "clx8k9r2c0007qwer1a2b3c4d",
      "name": "Checkout",
      "urlPath": "/checkout",
      "type": "page",
      "isPrimary": false,
      "createdAt": "2026-04-21T09:16:44.010Z",
      "website": {
        "id": "clx8k7m1b0003qwer8i9o0p1a",
        "name": "Acme Storefront",
        "url": "https://acme.example.com",
        "status": "CRITICAL",
        "projectId": "clx8k2p9a0001qwer4t5y6u7i",
        "environmentId": "clx8k4n7d0002qwer2s3d4f5g"
      },
      "latestCheck": {
        "timestamp": "2026-09-08T18:42:11.884Z",
        "success": false,
        "httpStatusCode": 503,
        "latencyMs": 4021,
        "errorType": "BAD_STATUS",
        "errorMessage": "Unexpected status code 503"
      }
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 50
}

latestCheck is null when a target has never been checked.

GET /uptime/search

Full-text search across your uptime targets. Matches the target name, the target URL path, or the website URL. Matching is case-insensitive.

Parameter	Type	Default	Max	Allowed values
`q`	string	— (required)	—	Any non-empty search term

q is required — omitting it, or passing only whitespace, returns 400. Results are capped at 20 and are not pageable; narrow your term rather than paging.

curl "https://api.usetrackz.app/api/public/v1/uptime/search?q=checkout" \
  -H "Authorization: Bearer $TRACKZ_TOKEN"

{
  "data": [
    {
      "id": "clx8k9r2c0007qwer1a2b3c4d",
      "name": "Checkout",
      "urlPath": "/checkout",
      "type": "page",
      "isPrimary": false,
      "createdAt": "2026-04-21T09:16:44.010Z",
      "website": {
        "id": "clx8k7m1b0003qwer8i9o0p1a",
        "name": "Acme Storefront",
        "url": "https://acme.example.com",
        "status": "CRITICAL",
        "projectId": "clx8k2p9a0001qwer4t5y6u7i",
        "environmentId": "clx8k4n7d0002qwer2s3d4f5g"
      },
      "latestCheck": {
        "timestamp": "2026-09-08T18:42:11.884Z",
        "success": false,
        "httpStatusCode": 503,
        "latencyMs": 4021,
        "errorType": "BAD_STATUS",
        "errorMessage": "Unexpected status code 503"
      }
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}

GET /uptime/{targetId}

Returns one uptime target plus its check history, newest first. Use the id of any item from GET /uptime or GET /uptime/search as {targetId}.

Parameter	Type	Default	Max	Allowed values
`from`	string	—	—	ISO 8601 date or date-time, e.g. `2026-09-01` or `2026-09-01T00:00:00Z`
`to`	string	—	—	ISO 8601 date or date-time
`limit`	integer	`50`	`200`	Any integer

from and to filter the check history by timestamp and can be used independently — pass just from for "everything since", just to for "everything until", or both for a window. A value that cannot be parsed as a date returns 400. An unknown targetId, or one belonging to another workspace, returns 404.

Note that limit caps the history at 200 here, not 100, and there is no page parameter — use from and to to move through a long history.

curl "https://api.usetrackz.app/api/public/v1/uptime/clx8k9r2c0007qwer1a2b3c4d?from=2026-09-01&to=2026-09-08&limit=100" \
  -H "Authorization: Bearer $TRACKZ_TOKEN"

{
  "target": {
    "id": "clx8k9r2c0007qwer1a2b3c4d",
    "name": "Checkout",
    "urlPath": "/checkout",
    "type": "page",
    "isPrimary": false,
    "createdAt": "2026-04-21T09:16:44.010Z",
    "website": {
      "id": "clx8k7m1b0003qwer8i9o0p1a",
      "name": "Acme Storefront",
      "url": "https://acme.example.com",
      "status": "CRITICAL",
      "projectId": "clx8k2p9a0001qwer4t5y6u7i",
      "environmentId": "clx8k4n7d0002qwer2s3d4f5g"
    },
    "latestCheck": {
      "timestamp": "2026-09-08T18:42:11.884Z",
      "success": false,
      "httpStatusCode": 503,
      "latencyMs": 4021,
      "errorType": "BAD_STATUS",
      "errorMessage": "Unexpected status code 503"
    }
  },
  "history": [
    {
      "id": "clx9m1t4e0011qwer5h6j7k8l",
      "timestamp": "2026-09-08T18:42:11.884Z",
      "success": false,
      "httpStatusCode": 503,
      "latencyMs": 4021,
      "ttfbMs": 3980,
      "dnsMs": 12,
      "errorType": "BAD_STATUS",
      "errorMessage": "Unexpected status code 503"
    },
    {
      "id": "clx9m0s3d0010qwer3f4g5h6j",
      "timestamp": "2026-09-08T18:41:09.512Z",
      "success": true,
      "httpStatusCode": 200,
      "latencyMs": 212,
      "ttfbMs": 188,
      "dnsMs": 11,
      "errorType": null,
      "errorMessage": null
    }
  ],
  "total": 2,
  "limit": 100
}

total is the number of history records matching your from/to window, which can exceed the number returned in history when it is larger than limit.

Errors

Every error returns a JSON body with a single message field:

{ "message": "Invalid API token" }

Status	When it happens
`400`	A parameter is malformed — `status` is not `up` or `down`, `q` is missing or blank, or `from`/`to` is not a valid ISO date.
`401`	The `Authorization` header is missing or is not a Bearer credential; or the token is malformed, unrecognised, or has been revoked.
`402`	The workspace is on the Free plan (or the legacy Starter plan). Upgrade to a paid plan to use the public API.
`404`	The `targetId` does not exist, or it belongs to a different workspace. Trackz answers both cases identically so the API never reveals whether another workspace's resource exists.
`405`	The request used a method other than `GET` or `HEAD`. The response includes an `Allow: GET` header. This is checked before authentication, so a `POST` without a token returns `405`, not `401`.

A revoked token is indistinguishable from an invalid one: both return 401 with the message Invalid API token.

Revoking a token

Open Settings → API Tokens in the dashboard.
Find the token in the list — match it by name, or by the trkz_… prefix and last 4 characters shown next to it.
Click the trash icon and confirm in the Revoke this token? dialog.

Revocation takes effect immediately. The token disappears from the list and every subsequent request made with it returns 401. Revoking cannot be undone — if you revoked the wrong token, create a new one and update whatever was using it.

Revoke a token as soon as you suspect it has leaked, when the script or service using it is retired, or when someone with access to it leaves your team.

Troubleshooting

Every request returns 401. Check that the header is exactly Authorization: Bearer <token>, with a single space after Bearer, and that the value starts with trkz_. A common cause is a shell variable that was never set, which silently sends Bearer with an empty value. Confirm the token still appears in Settings → API Tokens — if it is gone, it was revoked and you need a new one.

Every request returns 402. The workspace is on the Free or legacy Starter plan. The plan is re-checked on every request, so this also appears when a previously working token belongs to a workspace that has since downgraded.

A POST returns 405 instead of a helpful error. Version 1 is read-only. Use the dashboard for anything that changes data.

GET /uptime returns an empty list. Only targets on websites with uptime monitoring enabled are returned. Check that the website has uptime checks switched on, and that you are not filtering by a projectId or environmentId from a different workspace.

The id from GET /projects returns 404 on /uptime/{targetId}. These are different kinds of id. {targetId} is a monitored target id — take it from the id field of a GET /uptime item, not from a project or website.