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. 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/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
}

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