Skip to content

Twitter Analytics API

The Twitter Analytics API brings Twitter and X performance data into a product, reporting workflow, automation, or AI system through one consistent endpoint.

Recent tweets request
curl -X GET "{{API_BASE_URL}}/v1/analytics/?source=platform&platform=twitter&accountId=acc_tw_123&limit=10&page=1" \
 -H "x-access-key: your-api-key"
Illustrative request
Example line 1

curl -X GET "{{API_BASE_URL}}/v1/analytics/?source=platform&platform=twitter&accountId=acc_tw_123&limit=10&…

Illustrative request
Example line 2

-H "x-access-key: your-api-key"

Use it to retrieve analytics for an individual tweet, pull recent tweets from a connected account, filter by date, sort by performance, and paginate results for a content-performance dashboard.

What this endpoint returns and when to use it

This endpoint returns Twitter performance data in one normalized analytics structure, so dashboards and reporting tools do not need a separate Twitter-specific response format. Each result can carry aggregated metrics and a per-platform breakdown, with unsupported metric fields returned as null rather than omitted. That null handling matters in charts and exports: treat null as unavailable for that metric, not as zero, and keep impressions, likes, comments, shares, clicks, views, reach, saves, and engagementRate as distinct fields when building summaries.

Exact request contract

Send a GET request to {{API_BASE_URL}}/v1/analytics/ with the x-access-key header set to your API key. The trailing slash is part of the path. For connected-account retrieval, set source=platform, platform=twitter, and accountId to the connected Twitter account identifier. For a single tweet, pass the tweet ID as postId together with platform=twitter and the connected accountId. For stored published content, query by the stored postId instead of an external tweet ID. Before sending a request, check that accountId is present, that platform is exactly twitter, and that you have chosen the right retrieval mode: source=platform for recent content from the connected account, postId for a specific tweet or stored post.

Worked example: recent tweets from a connected account

The worked example in the request and response examples below shows recent tweets from a connected account using source=platform, platform=twitter, accountId=acc_tw_123, limit=10, and page=1. The captured response label for this example is 202. The response echoes success, total, page, and limit, then returns a posts array. Each post includes source, postId, content, publishedAt, an aggregated metrics object, and a platforms array. Inside platforms, platformPostId identifies the tweet on Twitter, platformPostUrl links to it, and metrics repeats the normalized metric fields for that platform entry. In the example, postId is null because the content came from the platform source rather than stored published content.

Sorting, date-range, and pagination rules

Use fromDate and toDate to narrow results to a reporting period. When omitted, fromDate starts 90 days before today and toDate ends today, and the maximum documented date range is 366 days. Use sortBy and order to rank content by a supported metric, then page through larger sets with page and limit. The default limit is 50 and the maximum is 100 results per page. A practical dashboard workflow is to pull a connected-account list with source=platform, sort by the metric your report cares about, paginate through all pages, and then use individual postId lookups when a user selects a specific tweet for detail.

Choosing the right retrieval mode

Choose source=platform when you need recent items straight from a connected Twitter account, including supported tweets that were not published through the stored-post workflow. Choose a stored postId when you need performance data for content already tracked as published content. Choose an external tweet ID as postId when you need analytics for a specific tweet that exists on the platform but was not stored as published content, providing platform=twitter and the connected accountId. If a metric such as reach, saves, views, or engagementRate is null, do not substitute zero; surface it as unavailable in the interface and exclude it from averages unless your reporting rules explicitly define how nulls are handled.

Dashboard and reporting workflow

Build the dashboard by combining connected-account retrieval for lists, individual tweet lookups for detail views, date filters for reporting periods, sorting for top-performing content, and pagination for complete result sets. Store platformPostId alongside the normalized metrics so a row in a table can link back to the original tweet. When exporting, preserve the distinction between aggregated metrics and per-platform metrics, and preserve null values so downstream analysis does not mistake unavailable data for zero performance.

Input contract for GET /v1/analytics/
ParameterRequirednessValues / formatDefault / limitPurpose
sourceDocumented for connected-account retrievalplatform (source=platform)Not statedRetrieve recent content directly from a connected Twitter account
platformRequired in documented examplestwitterNot statedSelect Twitter/X as the platform
accountIdRequired in documented examplesConnected Twitter account identifier, e.g. acc_tw_123Not statedIdentify the connected account for retrieval
postIdRequired for single-tweet / stored-post lookupTweet ID or stored postIdNot statedRetrieve analytics for a specific tweet or stored published post
fromDateOptionalDateDefaults to 90 days agoStart of reporting period
toDateOptionalDateDefaults to todayEnd of reporting period; maximum documented range 366 days
sortByOptionaldate, likes, comments, impressions, views, shares, saves, clicks, engagementNot statedRank returned content by a supported metric
orderOptionalAscending or descendingNot statedSort direction for sortBy
pageOptionalPage numberNot statedPagination page for list requests
limitOptionalResults per pageDefault 50; maximum 100Pagination page size

Exact captured contract; origin modularized as {{API_BASE_URL}}; captured response label: 202

Normalized response field map
FieldType in exampleMay be nullMeaning
successbooleanNoRequest success flag
totalnumberNoTotal results for the query
pagenumberNoCurrent page
limitnumberNoResults per page
postsarrayNoReturned posts
posts[].sourcestringNoRetrieval source, e.g. platform
posts[].postIdstring or nullYesStored post identifier; null for platform-sourced content in the example
posts[].contentstringNoPost content
posts[].publishedAtstring (ISO 8601)NoPublication timestamp
posts[].aggregatedobjectNoAggregated normalized metrics
posts[].aggregated.impressionsnumberNo in exampleImpressions metric
posts[].aggregated.reachnumber or nullYesReach metric; null when unavailable
posts[].aggregated.likesnumberNo in exampleLikes metric
posts[].aggregated.commentsnumberNo in exampleComments metric
posts[].aggregated.sharesnumberNo in exampleShares metric
posts[].aggregated.savesnumber or nullYesSaves metric; null when unavailable
posts[].aggregated.clicksnumberNo in exampleClicks metric
posts[].aggregated.viewsnumber or nullYesViews metric; null when unavailable
posts[].aggregated.engagementRatenumber or nullYesEngagement rate; null when unavailable
posts[].platformsarrayNoPer-platform breakdowns
posts[].platforms[].platformstringNoPlatform identifier, e.g. twitter
posts[].platforms[].platformPostIdstringNoTweet identifier on the platform
posts[].platforms[].platformPostUrlstringNoURL of the platform post
posts[].platforms[].metricsobjectNoNormalized metrics for this platform entry

Field map from captured response example; captured response label: 202

Failure matrix and request checks
ConditionWhat to checkExpected handling
Missing accountIdConfirm accountId is included for platform=twitter retrievalDo not send the request until the connected account identifier is present
External tweet ID lookupConfirm postId is the tweet ID, platform=twitter, and accountId is the connected accountUse the external platform post ID path rather than a stored postId
Stored published post lookupConfirm postId is the stored post identifierUse stored-post retrieval instead of source=platform
Unsupported metric returns nullCheck reach, saves, views, engagementRate and other metric fieldsTreat null as unavailable, not zero; do not average nulls as zero
limit over maximumConfirm limit is no greater than 100Reduce limit to 100 or less; default is 50
Date range over maximumConfirm fromDate to toDate span is no greater than 366 daysSplit the query into smaller date ranges
Missing trailing slashConfirm path is /v1/analytics/ exactlyUse {{API_BASE_URL}}/v1/analytics/ with the trailing slash preserved
Missing x-access-key headerConfirm the x-access-key header is presentAdd the header before retrying

Pre-flight checks derived from documented contract; no error status codes invented

Frequently asked questions

How do I retrieve analytics for a specific tweet?

Supply the tweet identifier in postId, set platform to twitter, and include the connected account's accountId.

Can I retrieve analytics for tweets I did not publish through the system?

Yes. An outside platform post identifier can be used. Send that identifier as postId, set platform to twitter, and include the connected accountId.

Can I retrieve tweets directly from the connected Twitter account?

Yes. Set source=platform, platform to twitter, and provide the connected accountId to fetch account content.

What analytics fields does the response contain?

Expect impressions, reach, likes, comments, shares, saves, clicks, views, and engagementRate in the shared shape. Any of those values may be null when the underlying metric is not available.

How far back can I query Twitter content?

Omitting fromDate starts the window 90 days before today, while omitting toDate ends it today. A single query may span at most 366 days.

Can I sort the returned Twitter content?

Yes. sortBy accepts date, likes, comments, impressions, views, shares, saves, clicks, or engagement, and order chooses ascending or descending direction.

How does pagination work?

For list calls, page selects the page and limit sets its size. The size starts at 50 when omitted and cannot exceed 100.

Can I use Twitter analytics to build a content-performance dashboard?

Yes. Combine account-level listing, single-tweet lookup, date bounds, metric ordering, and paging to feed your own content-performance dashboard.

Recent tweets response
{
    "success": true,
    "total": 1,
    "page": 1,
    "limit": 10,
    "posts": [
      {
        "source": "platform",
        "postId": null,
        "content": "A short example update.",
        "publishedAt": "2026-08-28T14:30:00Z",
        "aggregated": {
          "impressions": 0,
          "reach": null,
          "likes": 0,
          "comments": 0,
          "shares": 0,
          "saves": null,
          "clicks": 0,
          "views": null,
          "engagementRate": null
        },
        "platforms": [
          {
            "platform": "twitter",
            "platformPostId": "1961234567890123456",
            "platformPostUrl": "https://twitter.com/example/status/1961234567890123456",
            "metrics": {
              "impressions": 0,
              "reach": null,
              "likes": 0,
              "comments": 0,
              "shares": 0,
              "saves": null,
              "clicks": 0,
              "views": null,
              "engagementRate": null
            }
          }
        ]
      }
    ]
}