XTracker - Social Media Analytics

Start here

Overview

Every endpoint is available under /api and uses HTTP GET. Responses are JSON.

Dates should be supplied as ISO 8601 strings. Use the platform query parameter when the same handle may exist on more than one platform.

Values

Platforms

Platform	API value	Post term
X	`X`	tweets
Truth Social	`TRUTH_SOCIAL`	truths

Resource

Users

GET/users

Return all tracked users and their tracking periods. Inactive users are omitted unless requested.

Parameter	Type	Description
`platform`	string	Filter by X or TRUTH_SOCIAL.
`stats`	boolean	Include detailed posting statistics using the legacy response shape.
`includeInactive`	boolean	Include people without an active tracking period.

Example response

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "handle": "realDonaldTrump",
      "name": "Donald J. Trump",
      "platform": "TRUTH_SOCIAL",
      "avatarUrl": "https://...",
      "verified": true,
      "trackings": [],
      "_count": { "posts": 95 }
    }
  ]
}

Legacy mode: ?stats=true returns an array directly rather than the standard response envelope.

GET/users/[handle]

Return one tracked user by handle.

Parameter	Type	Description
`platform`	string	Disambiguate a handle that exists on multiple platforms.

Example request

GET /users/realDonaldTrump?platform=TRUTH_SOCIAL

GET/users/[handle]/posts

Return posts from a user, optionally constrained to a date range.

Parameter	Type	Description
`platform`	string	Select the account platform.
`startDate`	ISO date	Return posts published on or after this date.
`endDate`	ISO date	Return posts published on or before this date.
`timezone`	string	Use EST to interpret supplied dates as Eastern time.

GET/users/[handle]/trackings

Return every tracking period attached to a user.

Parameter	Type	Description
`platform`	string	Select the account platform.
`activeOnly`	boolean	Return only active tracking periods.

Resource

Trackings

GET/trackings

Return tracking periods across all users.

Parameter	Type	Description
`activeOnly`	boolean	Return only active periods. Defaults to true.

GET/trackings/[id]

Return one tracking period, optionally with calculated progress statistics.

Parameter	Type	Description
`includeStats`	boolean	Include totals, progress, pace, and daily metrics.

Example response

{
  "success": true,
  "data": {
    "id": "uuid",
    "title": "Week of Jan 15",
    "startDate": "2026-01-15T17:00:00.000Z",
    "endDate": "2026-01-22T16:59:59.000Z",
    "target": 100,
    "isActive": true,
    "stats": {
      "total": 95,
      "percentComplete": 95,
      "daily": []
    }
  }
}

Resource

Metrics

GET/metrics/[userId]

Return calculated metrics for one user.

Parameter	Type	Description
`type`	string	Metric grouping. Defaults to daily.
`startDate`	ISO date	Start of the metric window.
`endDate`	ISO date	End of the metric window.

Conventions

Responses

Standard responses use a consistent success envelope. Errors return the same shape with an error message.

Response shapes

// Success
{
  "success": true,
  "data": { ... },
  "message": "Optional message"
}

// Error
{
  "success": false,
  "error": "Error description"
}

Dates

Timezones

Dates are stored in UTC. Tracking windows are defined in America/New_York time.

Daily metric keys use M/D/YYYY in Eastern time.