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.
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"curl -X GET "{{API_BASE_URL}}/v1/analytics/?source=platform&platform=twitter&accountId=acc_tw_123&limit=10&…
-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.
| Parameter | Requiredness | Values / format | Default / limit | Purpose |
|---|---|---|---|---|
| source | Documented for connected-account retrieval | platform (source=platform) | Not stated | Retrieve recent content directly from a connected Twitter account |
| platform | Required in documented examples | Not stated | Select Twitter/X as the platform | |
| accountId | Required in documented examples | Connected Twitter account identifier, e.g. acc_tw_123 | Not stated | Identify the connected account for retrieval |
| postId | Required for single-tweet / stored-post lookup | Tweet ID or stored postId | Not stated | Retrieve analytics for a specific tweet or stored published post |
| fromDate | Optional | Date | Defaults to 90 days ago | Start of reporting period |
| toDate | Optional | Date | Defaults to today | End of reporting period; maximum documented range 366 days |
| sortBy | Optional | date, likes, comments, impressions, views, shares, saves, clicks, engagement | Not stated | Rank returned content by a supported metric |
| order | Optional | Ascending or descending | Not stated | Sort direction for sortBy |
| page | Optional | Page number | Not stated | Pagination page for list requests |
| limit | Optional | Results per page | Default 50; maximum 100 | Pagination page size |
Exact captured contract; origin modularized as {{API_BASE_URL}}; captured response label: 202
| Field | Type in example | May be null | Meaning |
|---|---|---|---|
| success | boolean | No | Request success flag |
| total | number | No | Total results for the query |
| page | number | No | Current page |
| limit | number | No | Results per page |
| posts | array | No | Returned posts |
| posts[].source | string | No | Retrieval source, e.g. platform |
| posts[].postId | string or null | Yes | Stored post identifier; null for platform-sourced content in the example |
| posts[].content | string | No | Post content |
| posts[].publishedAt | string (ISO 8601) | No | Publication timestamp |
| posts[].aggregated | object | No | Aggregated normalized metrics |
| posts[].aggregated.impressions | number | No in example | Impressions metric |
| posts[].aggregated.reach | number or null | Yes | Reach metric; null when unavailable |
| posts[].aggregated.likes | number | No in example | Likes metric |
| posts[].aggregated.comments | number | No in example | Comments metric |
| posts[].aggregated.shares | number | No in example | Shares metric |
| posts[].aggregated.saves | number or null | Yes | Saves metric; null when unavailable |
| posts[].aggregated.clicks | number | No in example | Clicks metric |
| posts[].aggregated.views | number or null | Yes | Views metric; null when unavailable |
| posts[].aggregated.engagementRate | number or null | Yes | Engagement rate; null when unavailable |
| posts[].platforms | array | No | Per-platform breakdowns |
| posts[].platforms[].platform | string | No | Platform identifier, e.g. twitter |
| posts[].platforms[].platformPostId | string | No | Tweet identifier on the platform |
| posts[].platforms[].platformPostUrl | string | No | URL of the platform post |
| posts[].platforms[].metrics | object | No | Normalized metrics for this platform entry |
Field map from captured response example; captured response label: 202
| Condition | What to check | Expected handling |
|---|---|---|
| Missing accountId | Confirm accountId is included for platform=twitter retrieval | Do not send the request until the connected account identifier is present |
| External tweet ID lookup | Confirm postId is the tweet ID, platform=twitter, and accountId is the connected account | Use the external platform post ID path rather than a stored postId |
| Stored published post lookup | Confirm postId is the stored post identifier | Use stored-post retrieval instead of source=platform |
| Unsupported metric returns null | Check reach, saves, views, engagementRate and other metric fields | Treat null as unavailable, not zero; do not average nulls as zero |
| limit over maximum | Confirm limit is no greater than 100 | Reduce limit to 100 or less; default is 50 |
| Date range over maximum | Confirm fromDate to toDate span is no greater than 366 days | Split the query into smaller date ranges |
| Missing trailing slash | Confirm path is /v1/analytics/ exactly | Use {{API_BASE_URL}}/v1/analytics/ with the trailing slash preserved |
| Missing x-access-key header | Confirm the x-access-key header is present | Add 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.
{
"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
}
}
]
}
]
}