API Reference
Analytics
Retrieve engagement metrics for published posts.
Get Post Analytics
GET /api/v1/analytics/posts/:id
Authorization: Bearer chirpie_sk_YOUR_KEYReturns engagement metrics for a published post. Metrics are cached for 1 hour — subsequent requests within that window return cached data.
Response 200 OK
{
"data": {
"post_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"impressions": 1250,
"likes": 42,
"retweets": 8,
"replies": 3,
"quotes": 1,
"bookmarks": 5,
"clicks": 15,
"fetched_at": "2026-03-23T10:30:00.000Z"
}
}Metrics
| Metric | Description |
|---|---|
impressions | Number of times the post was viewed |
likes | Number of likes |
retweets | Number of retweets |
replies | Number of replies |
quotes | Number of quote tweets |
bookmarks | Number of bookmarks |
clicks | Link clicks (may be null if not available) |
fetched_at | When metrics were last fetched from X |
Error Responses
| Status | Code | Condition |
|---|---|---|
400 | bad_request | Post not yet published or missing platform ID |
404 | not_found | Post not found |
502 | upstream_error | Failed to fetch from X (returns cached data if available) |
Analytics Retention
| Plan | Retention |
|---|---|
| Free | 48 hours |
| Starter | 30 days |
| Pro | 90 days |
| Scale | 365 days |
| Enterprise | 365 days |