Metadata

The metadata endpoint returns the website identity, dashboard header metrics, period information, metric deltas, and configured goal metrics for a website.

How It Works

The endpoint authenticates each request using your website's API token, which you can generate here. It resolves the requested period, fetches summary metrics, compares against the previous period when possible, and returns the website's configured goal metadata.

Sensitive fields such as user IDs, OAuth tokens, webhook URLs, and API token hashes are never returned.

Use Case

Use this endpoint as the first call when building a custom dashboard. It gives you website identity, top-line metrics, current visitors, and goal configuration in one response.

Endpoint

GET https://trackfox.app/api/v1/metadata

Authentication

This endpoint requires authentication using a Bearer token.

Authorization: Bearer tf_your_api_token_here

Query Parameters

Parameter	Type	Required	Description
websiteId	string	Yes	The unique identifier of your website
period	string	No	Time period to query. Defaults to last30d. Supported values: today, yesterday, last24h, last7d, last30d, wtd, mtd, ytd, all, custom
startDate	string	Only for period=custom	Custom period start date
endDate	string	Only for period=custom	Custom period end date
timezone	string	No	Timezone used for period calculations. Defaults to UTC

Response Format

{
  "website": {
    "id": "your_website_id",
    "name": "Example",
    "domain": "example.com",
    "primaryHostname": "www.example.com",
    "hostnames": ["example.com", "www.example.com"],
    "createdAt": "2026-01-10T12:00:00.000Z",
    "hasReceivedEvents": true,
    "theme": {
      "primaryColor": "#111827",
      "secondaryColor": "#6b7280"
    },
    "goal": {
      "type": "revenue",
      "customEventName": null,
      "property": null,
      "propertyValue": null
    }
  },
  "period": {
    "label": "last30d",
    "startDate": "2026-04-15T00:00:00.000Z",
    "endDate": "2026-05-14T23:59:59.999Z",
    "timezone": "UTC",
    "interval": "day"
  },
  "metrics": {
    "uniqueVisitors": 1240,
    "totalPageviews": 3188,
    "bounceRate": 42,
    "avgSessionTime": 96,
    "currentVisitors": 5
  },
  "deltas": {
    "visitors": 120,
    "visitorsPercentage": 11,
    "bounceRate": -3,
    "avgSessionTime": 14,
    "avgSessionTimePercentage": 17
  },
  "goalMetrics": {
    "goalType": "revenue",
    "totalRevenue": 129000,
    "transactions": 27
  }
}

Response Fields

• website: Public website identity, theme, and goal configuration
• period: The resolved date range, timezone, and chart interval.
• metrics: Header metrics for visitors, pageviews, bounce rate, average session time, and realtime visitors.
• deltas: Comparison values against the previous equivalent period. Values are null when period=all.
• goalMetrics: Revenue or custom-event metrics for the configured website goal.

Error Responses

400 Bad Request

The request is missing websiteId, uses an invalid period, or has an invalid custom date range.

401 Unauthorized

The Authorization header is missing, malformed, or contains an invalid API token.

404 Not Found

No website exists for the supplied websiteId.

500 Internal Server Error

An unexpected server error occurred.

Example Usage

cURL Request

curl "https://trackfox.app/api/v1/metadata?websiteId=your_website_id&period=last30d" \
  -H "Authorization: Bearer tf_your_api_token_here"

JavaScript Fetch

const response = await fetch(
  "https://trackfox.app/api/v1/metadata?websiteId=your_website_id&period=last30d",
  {
    headers: {
      Authorization: "Bearer tf_your_api_token_here",
    },
  },
);

const data = await response.json();
console.log(data.metrics);

Next Steps

• Fetch chart data
• Fetch realtime visitors