Data API Skill

This is the TrackJS Data API skill exactly as an AI agent reads it. It is written for the agent, so it speaks to the agent directly. See the AI Agents page for what the skill does and how to install it, or download the raw file.

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

[{
  "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).