---
name: trackjs-data-api
description: Query and analyze TrackJS error monitoring data through the TrackJS Data API. Use when the user wants to retrieve JavaScript errors, error counts, error trends, page views, or usage statistics from TrackJS. Triggers include "TrackJS errors", "error report", "top errors", "error spike", "error rate", or exporting TrackJS data.
---

# TrackJS Data API

TrackJS is a JavaScript error monitoring service. This skill covers the Data API, which retrieves error and page view data from a TrackJS account for reporting, analysis, and export.

Full documentation: https://docs.trackjs.com/data-api/

## Authentication

Two credentials are required. Both are visible only to Account Owners at https://my.trackjs.com/account/organization:

- **Customer ID**: goes in the URL path of every request.
- **API Key**: sent in the `Authorization` header.

```
curl -H "Authorization: {API_KEY}" "https://api.trackjs.com/{CUSTOMER_ID}/v1/errors"
```

If setting a header is inconvenient, pass the API Key as a `key` querystring parameter instead.

Ask the user for their Customer ID and API Key if not provided. Never log or echo the API Key back in output.

## Base URL and conventions

- Base URL: `https://api.trackjs.com/{CUSTOMER_ID}/v1/`
- All endpoints are `GET` and return JSON.
- Dates are ISO 8601 strings (`2026-07-01T00:00:00Z`). Time precision is within 1 second.
- **Paging**: endpoints return 20 results by default. Use `page` and `size` (1-1000) querystring parameters. Responses include a `metadata` object with `page`, `size`, and `hasMore` (some endpoints also return `totalCount`).
- **Sorting**: where supported, use `sort={field}|{direction}`, for example `sort=usercount|desc`. Remember to URL-encode the pipe (`%7C`) when needed.
- Aggregate endpoints return `count` (number of errors) and `userCount` (number of distinct users affected). `userCount` is usually the better measure of impact.

## Endpoints

| Endpoint | Path | Returns |
|---|---|---|
| Errors | `/v1/errors` | Individual error instances, newest first |
| Errors by Day | `/v1/errors/daily` | Error count per day |
| Errors by Hour | `/v1/errors/hourly` | Error count per hour |
| Errors by Message | `/v1/errors/messages` | Error counts grouped by message |
| Errors by URL | `/v1/errors/urls` | Error counts grouped by page URL |
| Page Views by Day | `/v1/hits/daily` | Page view count per day |
| Page Views by Hour | `/v1/hits/hourly` | Page view count per hour |
| Usage by Hour | `/v1/usage/hourly` | Account-wide usage stats per hour |

### Errors

`GET /v1/errors`: individual errors, sorted by date descending.

Parameters (all optional):

- `application`: filter to one Application key.
- `startDate`, `endDate`: ISO 8601 date range.
- `query`: full-text search across error message, URLs, metadata, and user IDs. Same behavior as the TrackJS Dashboard search.
- `includeStack`: boolean. Include the `stackTrace` array (split on newlines). Off by default because stacks are large.
- `page`, `size`: paging.

Response items include: `message`, `timestamp`, `url`, `id`, `browserName`, `browserVersion`, `entry` (how the error was captured: ajax, direct, catch, console, window), `line`, `column`, `file`, `userId`, `sessionId`, `status`, `trackJsUrl` (deep link to the error in the dashboard), `metadata` (array of key/value pairs), and `stackTrace` when requested.

```
curl -H "Authorization: {API_KEY}" \
  "https://api.trackjs.com/{CUSTOMER_ID}/v1/errors?startDate=2026-07-01&endDate=2026-07-14&includeStack=true"

curl -H "Authorization: {API_KEY}" \
  "https://api.trackjs.com/{CUSTOMER_ID}/v1/errors?query=Cannot%20read%20property"
```

### Errors by Day

`GET /v1/errors/daily`: error counts per day, sorted by date descending.

Parameters: `application`, `startDate`, `endDate`, `page`, `size`, `sort` (fields `date`, `count`, `usercount`, default `date|desc`).

Response items: `key` (day timestamp), `count`, `userCount`, `trackJsUrl`.

### Errors by Hour

`GET /v1/errors/hourly`: error counts per hour, sorted by date descending.

Same parameters and response shape as Errors by Day, with hourly `key` values. Useful for pinpointing when a spike started.

### Errors by Message

`GET /v1/errors/messages`: error counts grouped by message, sorted by count descending.

Parameters: `application`, `startDate`, `endDate`, `page`, `size`, `sort` (fields `count`, `usercount`, default `count|desc`).

Response items: `key` (the error message), `count`, `userCount`, `lastSeen`, `status`, `trackJsUrl`.

This is the best endpoint for "what are my top errors". Sort by `usercount|desc` to rank by user impact rather than raw volume:

```
curl -H "Authorization: {API_KEY}" \
  "https://api.trackjs.com/{CUSTOMER_ID}/v1/errors/messages?sort=usercount|desc"
```

### Errors by URL

`GET /v1/errors/urls`: error counts grouped by page URL, sorted by count descending.

Parameters: `application`, `startDate`, `endDate`, `page`, `size`, `sort` (fields `count`, `usercount`, default `count|desc`).

Response items: `key` (the page URL), `count`, `userCount`, `trackJsUrl`.

### Page Views by Day

`GET /v1/hits/daily`: page view counts per day, sorted by date descending.

Parameters: `application`, `startDate`, `endDate`, `page`, `size`.

Response items: `key` (day timestamp), `count`.

### Page Views by Hour

`GET /v1/hits/hourly`: page view counts per hour, sorted by date descending.

Same parameters and response shape as Page Views by Day, with hourly keys.

### Usage by Hour

`GET /v1/usage/hourly`: account-wide usage statistics per hour, sorted by date ascending. Not broken down by application, and does not support the `application` parameter.

Parameters: `startDate`, `endDate`.

Response is a plain array (no `data`/`metadata` wrapper):

```json
[{
  "timestamp": "2023-01-18T07:00:00+00:00",
  "pageViews": 556,
  "totalErrors": 3126,
  "processedErrors": 2762,
  "ignoredErrors": 352,
  "droppedErrors": 0,
  "errorsPerPageView": 5.622
}]
```

## Write endpoints (rarely needed)

These are the endpoints the TrackJS browser and node agents send data to. They do not require the API Key.

- **Capture**: `POST https://capture.trackjs.com/capture?token={TOKEN}` sends an error report (JSON body, max 100 KB, `Content-Type: text/plain`). The `token` comes from https://my.trackjs.com/install and is different from the API Key. Returns 200/202 regardless of validity. See https://docs.trackjs.com/data-api/capture/ for the payload schema.
- **Usage**: `GET https://usage.trackjs.com/usage.gif?token={TOKEN}` records one page view. Returns a 1x1 gif.

Only use these when the user explicitly wants to send custom errors or page views. For normal error reporting, recommend the TrackJS browser or node agent instead.

## Common workflows

**Top errors by user impact (last 7 days)**

1. `GET /v1/errors/messages?startDate={7d ago}&sort=usercount|desc&size=25`
2. Report `key`, `count`, `userCount`, `lastSeen`. Include `trackJsUrl` so the user can open each error in the dashboard.

**Investigate an error spike**

1. `GET /v1/errors/hourly?startDate={range}` to find when the spike started.
2. `GET /v1/hits/hourly` for the same range. If page views rose too, the spike may just be traffic.
3. `GET /v1/errors/messages?startDate={spike start}` to find which messages drove it.
4. `GET /v1/errors?query={message}&includeStack=true` to pull examples with stack traces.

**Error rate over time**

1. Fetch `/v1/errors/daily` and `/v1/hits/daily` for the same range.
2. Divide error count by page view count per day. Or use `/v1/usage/hourly`, which returns `errorsPerPageView` precomputed.

**Export all errors for a date range**

Loop `/v1/errors?startDate={start}&endDate={end}&size=1000&page={n}`, incrementing `page` until `metadata.hasMore` is false.

## Tips

- Prefer aggregate endpoints (`/messages`, `/daily`, `/urls`) over paging through raw `/errors` when the user wants summaries. They are one request instead of many.
- Every result includes a `trackJsUrl` deep link into the TrackJS dashboard. Include these links in reports.
- A 401 or 403 response means the Customer ID or API Key is wrong, or the user is not an Account Owner.
- For Node.js projects, the official client wraps this API: `npm install trackjs-api-client` (https://github.com/TrackJs/trackjs-api-client-js).