Measure an X account's engagement rate

POST/data-api/v2/tools/engagement-calculator

Get a key All 127 endpoints OpenAPI spec

Scope: tools:use
Freshness: live read
Group: Tools
Platforms: 1 of 7

What this endpoint answers

Computes the true engagement rate from recent posts rather than from follower count alone. Returns per-interaction rates, size-adjusted benchmarks, the best and worst performing post, a recent trend, and the full sampled post list with per-post rates.

This is a live read: it goes to the platform at request time, returns cache_age_s = 0, and is metered against a separate live-per-minute bucket on top of your tier. It needs the tools:use scope (Tools): Run the analysis tools: valuation, follower audit, scoring, and more.

Good to know

Costs money: this endpoint bills twitterapi.io credits per call. Metered as a live call.
Returns 503 not_configured when TWITTERAPI_IO_KEY is unset, and 502 upstream_error when the credit pool is exhausted or the upstream fails. It never returns an empty 200.
Ignores NEXT_PUBLIC_USE_MOCK_DATA: the X tools always read live data and have no mock path.
The website's captcha and per-visitor daily caps do not apply here; your API key's tier limits do.
engagement_rate is a share of followers. view_rate is a share of followers too, so it exceeds 100 for accounts whose reach is larger than their following.
`posts` carries every sampled post; it is the largest part of the payload.

Parameters

This endpoint takes no path or query parameters.

Request body

handlestringrequired
X handle. Accepts a bare name, @name, or a profile URL. Also accepted as `username`.

Example request body

{
  "handle": "elonmusk"
}

Call it

Authenticate with a bearer token or the x-api-key header. Keys are server-to-server credentials. Never embed one in front-end code - call the API from your own backend and forward the result.

curl

curl -X POST "https://crmsolid.com/data-api/v2/tools/engagement-calculator" \
  -H "Authorization: Bearer psk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"handle":"elonmusk"}'

JavaScript

const res = await fetch("https://crmsolid.com/data-api/v2/tools/engagement-calculator", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CRM_SOLID_DATA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "handle": "elonmusk"
  }),
});

if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`${error.code}: ${error.message} (${error.request_id})`);
}

const { data, meta } = await res.json();

Python

import json
import os

import requests

body = json.loads("""
{
  "handle": "elonmusk"
}
""")

res = requests.post(
    "https://crmsolid.com/data-api/v2/tools/engagement-calculator",
    headers={"Authorization": f"Bearer {os.environ['CRM_SOLID_DATA_API_KEY']}"},
    json=body,
    timeout=30,
)
res.raise_for_status()

payload = res.json()
data, meta = payload["data"], payload["meta"]

Keys look like psk_live_... for production keys, psk_test_... for test keys and are minted in the panel.

What comes back

Success is { data, meta }. Failure is { error: { code, message, request_id } }. The body below is the spec's own example: the values in it are illustrative readings, not live numbers.

Profile handle: levelsio
Profile twitter id: 10634622
Profile name: levelsio
Profile avatar url: https://pbs.twimg.com/profile_images/1719614758452781056/6Qt3xLpc.jpg
Profile verified: yes
Profile followers: 612,440
Profile following: 1,832
Profile total posts: 61,204
Profile created at: 11/27/2007, 9:12:44 AM
Profile account age days: 6,844
Engagement engagement rate: 1.24
Engagement median engagement rate: 0.92
Engagement consistency: 61
Engagement avg likes: 5,420
Engagement avg retweets: 388
Engagement avg replies: 612
Engagement avg quotes: 74
Engagement avg views: 481,200
Engagement avg bookmarks: 402
Engagement avg engagement per post: 6,496
Engagement total engagement: 129,920
Rates like rate: 0.885
Rates retweet rate: 0.063
Rates reply rate: 0.1
Rates view rate: 78.5
Rates bookmark rate: 0.066
Rates virality rate: 0.075
Rates conversation rate: 9.4

200 POST /tools/engagement-calculator

{
  "data": {
    "profile": {
      "handle": "levelsio",
      "twitter_id": "10634622",
      "name": "levelsio",
      "avatar_url": "https://pbs.twimg.com/profile_images/1719614758452781056/6Qt3xLpc.jpg",
      "verified": true,
      "followers": 612440,
      "following": 1832,
      "total_posts": 61204,
      "created_at": "2007-11-27T09:12:44.000Z",
      "account_age_days": 6844
    },
    "engagement": {
      "engagement_rate": 1.24,
      "median_engagement_rate": 0.92,
      "consistency": 61,
      "avg_likes": 5420,
      "avg_retweets": 388,
      "avg_replies": 612,
      "avg_quotes": 74,
      "avg_views": 481200,
      "avg_bookmarks": 402,
      "avg_engagement_per_post": 6496,
      "total_engagement": 129920
    },
    "rates": {
      "like_rate": 0.885,
      "retweet_rate": 0.063,
      "reply_rate": 0.1,
      "view_rate": 78.5,
      "bookmark_rate": 0.066,
      "virality_rate": 0.075,
      "conversation_rate": 9.4,
      "view_to_engagement_rate": 1.35,
      "like_dominance": 83.4
    },
    "rating": "excellent",
    "rating_score": 88,
    "benchmarks": {
      "excellent": 1.2,
      "good": 0.7,
      "average": 0.35,
      "below": 0.15
    },
    "reach": {
      "estimated_reach": 481200,
      "follower_following_ratio": 334.3,
      "posting_frequency": 8.9
    },
    "posts_analyzed": 20,
    "trend": "improving",
    "best_post": {
      "id": "1789231114023874812",
      "text": "Shipped it.",
      "likes": 24100,
      "retweets": 1420,
      "replies": 918,
      "quotes": 210,
      "views": 2140000,
      "bookmarks": 1802,
      "engagement_rate": 1.24,
      "created_at": "2026-08-11T07:40:12.000Z"
    },
    "worst_post": null,
    "posts": [],
    "summary": {
      "size_category": "100K-1M followers"
    }
  },
  "meta": {
    "request_id": "req_9f2c41a8b3d5",
    "generated_at": "2026-08-23T09:14:02.317Z",
    "took_ms": 42,
    "cache_age_s": 0
  }
}

The meta block

request_idstringrequired
Unique id for this request. Quote it in a support ticket.
generated_atstringrequired
Server time the response was produced.
took_msintegerrequired
Milliseconds spent server-side.
pagePageoptional
sourcestringoptional
Which backend served the payload, for endpoints with more than one.
cache_age_sintegeroptional
Age of the underlying data in seconds. 0 for live reads.

When it fails

POST /tools/engagement-calculator documents 7 failure statuses. Branch on error.code, which is stable and enumerated; message is prose and may change.

401Unauthorizedunauthorized | invalid_key
No key was presented, or the key is unknown, revoked or expired.
402PaymentRequiredpayment_required | subscription_inactive
The key is valid but the plan behind it cannot serve the call: the included requests are spent and overage is switched off, capped or unfunded (payment_required), or the billing period lapsed and was not renewed (subscription_inactive). Retrying does not help; paying does. The X-Plan-* headers on this response say how far past the line you are.
Carries X-Plan, X-Plan-Limit, X-Plan-Overage, X-Plan-Period-End, X-Plan-Remaining.
403Forbiddenforbidden_scope | forbidden_ip
The key is valid but not allowed to make this call: it lacks the scope, or the request came from an address outside the key's allowlist.
422InvalidRequestinvalid_request
A parameter is malformed, out of range or mutually exclusive with another. `details` names the offending fields.
429RateLimitedrate_limited | quota_exceeded
Either the burst ceiling for the current minute or the daily quota is spent. Distinguish with the code: rate_limited clears within the minute, quota_exceeded does not clear until 00:00 UTC.
Carries Retry-After, X-Quota-Limit, X-Quota-Remaining, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-Request-Id.
500InternalErrorinternal_error
Something failed on our side. Internals are never leaked; quote the request id.
503Unavailableupstream_timeout | upstream_error | not_configured
The request could not be served right now. BRANCH ON error.code, not on the status: 'upstream_timeout' means a source was too slow (this is what a catalog query hitting its 15-second statement timeout returns, so it is reachable from any endpoint that reads the corpus, not only the live-scrape ones) and the same call is worth retrying with backoff - narrowing it with a smaller limit, a filtered scope or a less popular account makes it far less likely; 'upstream_error' means a source was unreachable, so back off further; 'not_configured' means the capability has no backing service in this deployment, and retrying will never help.

Every response carries X-Request-Id and meta.request_id. Quote it in support requests.

Coverage and limits

This endpoint covers X. Rate limits come from the tier on your key.

Tier	Requests a minute	Requests a day	Live reads a minute
free	30	1,000	5
standard	120	25,000	20
pro	600	250,000	60
unlimited	6,000	10,000,000	600

Live reads count against the live column as well as the ordinary one, so a burst of them runs out of the live bucket first. Every response reports where you stand in X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and the X-Plan headers.

Start calling it

A key takes a minute to mint in the panel, no card. The reference covers authentication, the envelope, scopes, rate limits and every error code in one page.

Get a key All 127 endpoints Full reference What the Data API is

Reference path: /data-api/reference/tools-engagement-calculator