Analytics

Retrieve engagement metrics, timeseries data, post analytics, and more.

Postman CollectionDownload the ready-made collection with all endpoints pre-configured.

Use with Claude, ChatGPT & moreConnect any AI assistant to BlackTwist via our MCP server. No code required.

The providerUserId parameter is the platform-specific user ID (e.g. your Threads numeric ID), which you can obtain from the /providers endpoint.Paid plan required for the following endpoints. If the account (or its team owner) does not have an active paid plan, these endpoints return 403 Forbidden:

GET /api/v1/analytics/timeseries
GET /api/v1/analytics/posts
GET /api/v1/analytics/followers

All other analytics endpoints (/metrics, /consistency, /daily-recap, /recommendations) are available on all plans.

Get Metrics

`GET /api/v1/analytics/metrics`

Returns aggregated engagement metrics (views, likes, replies, reposts, quotes) for a date range with percentage change vs. the previous period.Query Parameters:

providerUserId (required) — Platform user ID
from (optional) — Start date (defaults to 7 days ago)
to (optional) — End date (defaults to today)
teamId (optional) — Team ID

Request

curl "https://blacktwist.app/api/v1/analytics/metrics?providerUserId=12345678&from=2025-03-01&to=2025-03-31" \
  -H "Authorization: Bearer bt_api_..."

Response

{
  "views": { "value": 15200, "percentageChange": 12.5 },
  "likes": { "value": 340, "percentageChange": -3.2 },
  "replies": { "value": 85, "percentageChange": 8.1 },
  "reposts": { "value": 42, "percentageChange": 15.0 },
  "quotes": { "value": 12, "percentageChange": 0 },
  "period": {
    "from": "2025-03-01T00:00:00.000Z",
    "to": "2025-03-31T23:59:59.999Z"
  }
}

Get Timeseries 🔒 Paid plan

`GET /api/v1/analytics/timeseries`

Returns daily data points for a single metric over a date range. Requires a paid plan.Query Parameters:

providerUserId (required) — Platform user ID
metric (required) — One of: VIEWS, LIKES, REPLIES, REPOSTS, QUOTES, FOLLOWERS_COUNT
from (required) — Start date
to (required) — End date
teamId (optional) — Team ID

Request

curl "https://blacktwist.app/api/v1/analytics/timeseries?providerUserId=12345678&metric=VIEWS&from=2025-03-01&to=2025-03-31" \
  -H "Authorization: Bearer bt_api_..."

Response

{
  "metric": "VIEWS",
  "points": [
    { "date": "2025-03-01", "value": 520 },
    { "date": "2025-03-02", "value": 480 },
    { "date": "2025-03-03", "value": 610 }
  ],
  "count": 3
}

Get Post Analytics 🔒 Paid plan

`GET /api/v1/analytics/posts`

Returns per-post analytics for published posts in a date range. Returns up to 100 posts, newest first unless you pass sortBy. Sorting and filters run over the whole range before the cap, and total is the number of matching posts. Requires a paid plan.Query Parameters:

providerUserId (required) — Platform user ID
from (required) — Start date
to (required) — End date
teamId (optional) — Team ID
sortBy (optional) — timestamp (default), views, likes, replies, reposts, quotes or engagementRate
sortOrder (optional) — asc or desc (default)
search (optional) — Only posts whose text contains this string (case-insensitive)
tagNames (optional) — Comma-separated tag names; only posts carrying at least one of them

Request

curl "https://blacktwist.app/api/v1/analytics/posts?providerUserId=12345678&from=2025-03-01&to=2025-03-31" \
  -H "Authorization: Bearer bt_api_..."

Response

{
  "posts": [
    {
      "mediaId": "threads_abc123",
      "text": "My top-performing post about...",
      "timestamp": "2025-03-15T09:00:00.000Z",
      "permalink": "https://threads.net/@johndoe/post/abc123",
      "provider": "THREADS",
      "analytics": {
        "views": 5200,
        "likes": 120,
        "replies": 35,
        "reposts": 18,
        "quotes": 5,
        "engagementRate": 3.42
      }
    }
  ],
  "count": 1,
  "total": 1
}

Get Follower Growth 🔒 Paid plan

`GET /api/v1/analytics/followers`

Returns daily follower count data points and total growth for a date range. Requires a paid plan.Query Parameters:

providerUserId (required) — Platform user ID
from (required) — Start date
to (required) — End date
teamId (optional) — Team ID

Request

curl "https://blacktwist.app/api/v1/analytics/followers?providerUserId=12345678&from=2025-03-01&to=2025-03-31" \
  -H "Authorization: Bearer bt_api_..."

Response

{
  "points": [
    { "date": "2025-03-01", "followers": 1200 },
    { "date": "2025-03-15", "followers": 1280 },
    { "date": "2025-03-31", "followers": 1350 }
  ],
  "count": 3,
  "totalGrowth": 150
}

Get Consistency

`GET /api/v1/analytics/consistency`

Returns your posting consistency over the last 365 days, including current and record posting streaks.Query Parameters:

providerUserId (required) — Platform user ID
teamId (optional) — Team ID

Request

curl "https://blacktwist.app/api/v1/analytics/consistency?providerUserId=12345678" \
  -H "Authorization: Bearer bt_api_..."

Response

{
  "days": [
    { "date": "2025-03-01", "count": 2 },
    { "date": "2025-03-02", "count": 1 },
    { "date": "2025-03-04", "count": 3 }
  ],
  "totalPosts": 156,
  "daysWithPosts": 82,
  "currentStreak": 14,
  "recordStreak": 30
}

Get Daily Recap

`GET /api/v1/analytics/daily-recap`

Returns a summary of yesterday's activity including new followers and posts published.Query Parameters:

providerUserId (required) — Platform user ID
teamId (optional) — Team ID

Request

curl "https://blacktwist.app/api/v1/analytics/daily-recap?providerUserId=12345678" \
  -H "Authorization: Bearer bt_api_..."

Response

{
  "date": "2025-03-14",
  "newFollowers": 12,
  "postsCount": 3
}

Get Recommendations

`GET /api/v1/analytics/recommendations`

Returns posting recommendations based on the last 30 days of data, including best posting hours and top-performing posts.Query Parameters:

providerUserId (required) — Platform user ID
teamId (optional) — Team ID

Request

curl "https://blacktwist.app/api/v1/analytics/recommendations?providerUserId=12345678" \
  -H "Authorization: Bearer bt_api_..."

Response

{
  "currentStreak": 14,
  "recordStreak": 30,
  "totalRecentPosts": 45,
  "bestPostingHoursUtc": [
    { "hour": 13, "avgEngagement": 4.2, "postCount": 8 },
    { "hour": 9, "avgEngagement": 3.8, "postCount": 12 },
    { "hour": 17, "avgEngagement": 3.1, "postCount": 6 }
  ],
  "topPerformingPosts": [
    {
      "text": "My best post about content strategy...",
      "timestamp": "2025-03-10T13:00:00.000Z",
      "engagementRate": 5.2,
      "likes": 180,
      "views": 8500
    }
  ]
}

Posts

Follow-ups