Twitter Profile Analyzer — X (Twitter) Profile Intelligence API for AI Agents & Social Listening

Twitter Profile Analyzer turns X (Twitter) handles into full profile intelligence — typed JSON rows, schema below. Give it a list of usernames (or profile URLs) and it returns one structured dataset item per profile with follower/following/post counts, bio, verified status, join date, avatar, website, location, and derived analysis fields (audience tier, follower ratio). Built for social-listening agents, influencer vetting, competitive intelligence, and audience analysis pipelines — no Twitter login, cookies, or API keys required.

Why agents use this actor

• Deterministic typed output — every row conforms to the published dataset schema; fields never change type or disappear between runs.
• Real profile metrics — live follower, following, post, and like counts plus bio, verification, and account age, not just page metadata.
• Cost-predictable — one dataset item per requested profile, priced per event, so autonomous agents can budget a run before starting it.
• No auth needed — no Twitter/X login, cookies, or API keys.
• Clear error semantics — per-item failures carry an error field, a run-level SUMMARY record aggregates failures, and the run exits non-zero on invalid input or total failure. Never a silent empty success.
• Rate-limit handling built in — automatic retry with exponential backoff on HTTP 429 and 5xx responses, 30-second request timeouts.

Input schema

Field	Type	Required	Default	Description
usernames	array of strings	Yes	—	X (Twitter) usernames/handles to analyze, with or without @ (e.g. "naval" or "@naval"). Full profile URLs are also accepted and normalized.
handles	array of strings	No	—	Alias for usernames; merged with it.
username	string	No	—	Convenience alias: a single handle instead of the array.
url	string	No	—	A single profile URL (advanced; merged with usernames).
urls	array of strings	No	—	Profile URLs (advanced; merged with usernames).
startUrls	array	No	—	Profile URLs as {"url": ...} request objects or plain strings (advanced; merged with usernames).
maxRequestsPerCrawl	integer	No	20	Upper bound on unique profiles processed per run.
proxyConfiguration	object	No	—	Proxy configuration (reserved; lookups run directly without a proxy).

Twitter Profile Output Schema

One dataset row per unique profile. Modes: success rows (profile resolved) and failure rows (profile not found, or the request failed after retries).

Field	Type	Nullable	Rows	Description
url	string	no	all	Canonical profile URL, e.g. https://x.com/naval.
username	string	yes	all	Handle without @, canonical casing on success rows.
statusCode	integer	yes	all	HTTP status of the lookup (200 on success, 404 when the profile does not exist). Null on network failure.
ok	boolean	no	all	true only when the profile was resolved with full data.
title	string	yes	all	Profile page title, e.g. Naval (@naval) / X. Null on failure rows.
name	string	yes	success	Display name.
followers	integer	yes	success	Follower count.
following	integer	yes	success	Accounts the profile follows.
tweets	integer	yes	success	Total posts.
likes	integer	yes	success	Total likes the account has given.
bio	string	yes	success	Profile bio text.
verified	boolean	yes	success	Verified status.
joinDate	string	yes	success	Account creation date, ISO 8601.
avatarUrl	string	yes	success	Profile picture URL.
website	string	yes	success	Website from the profile, if set.
location	string	yes	success	Location from the profile, if set.
audienceTier	string	yes	success	Derived from followers: nano (<1K), micro (1K–10K), mid (10K–100K), macro (100K–1M), mega (1M+).
followerRatio	number	yes	success	Followers ÷ following, rounded to 2 decimals; null when following is 0.
error	string	yes	failure only	Why the lookup failed (Profile not found, network error message).

Success row example:

{
  "url": "https://x.com/naval",
  "username": "naval",
  "statusCode": 200,
  "ok": true,
  "title": "Naval (@naval) / X",
  "name": "Naval",
  "followers": 3858834,
  "following": 1,
  "tweets": 27127,
  "likes": 299359,
  "bio": "Incompressible",
  "verified": true,
  "joinDate": "2007-02-01T23:05:04.000Z",
  "avatarUrl": "https://pbs.twimg.com/profile_images/1256841238298292232/ycqwaMI2_normal.jpg",
  "website": "https://nav.al",
  "location": null,
  "audienceTier": "mega",
  "followerRatio": 3858834
}

Failure row example:

{
  "url": "https://x.com/thishandledoesnotexist12345",
  "username": "thishandledoesnotexist12345",
  "statusCode": 404,
  "ok": false,
  "title": null,
  "error": "Profile not found"
}

Error semantics

• Invalid input (no usernames or URLs resolve): the run fails fast with exit code 1 and status message No profiles to analyze. Provide "usernames" (or url/urls/startUrls). Nothing is pushed to the dataset.
• Profile not found / suspended: the row is pushed with ok: false, statusCode: 404, and error: "Profile not found". Other profiles in the run are unaffected.
• Partial failure: failed profiles produce a dataset row with an error field; successful profiles are unaffected. The run still succeeds.
• Total failure (every lookup failed): all failure rows are pushed, then the run exits with code 1 so agents can detect it without inspecting items.
• SUMMARY record: every run writes a SUMMARY key-value record { requested, succeeded, failed, failures: [{url, username, error}] } — poll this for cheap run-level health checks and retry logic.
• Retries: HTTP 429/500/502/503/504 and network errors are retried up to 3 attempts with exponential backoff before a row is marked failed.

Use from AI agents (MCP)

{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com/?tools=apricot_blackberry/twitter-profile-analyzer",
      "headers": { "Authorization": "Bearer <YOUR_APIFY_TOKEN>" }
    }
  }
}

Works in Claude, Cursor, ChatGPT deep research connectors, and any MCP client; the input schema above is the tool's parameter schema.

Use from code

curl:

curl -X POST "https://api.apify.com/v2/acts/apricot_blackberry~twitter-profile-analyzer/run-sync-get-dataset-items?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"usernames": ["naval"]}'

JavaScript (apify-client):

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('apricot_blackberry/twitter-profile-analyzer').call({
  usernames: ['naval'],
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);

Python (apify_client):

from apify_client import ApifyClient

client = ApifyClient(os.environ["APIFY_TOKEN"])
run = client.actor("apricot_blackberry/twitter-profile-analyzer").call(
    run_input={"usernames": ["naval"]}
)
items = client.dataset(run["defaultDatasetId"]).list_items().items
print(items)

Use from automation platforms

• n8n / Make / Zapier: use the native Apify integration and choose apricot_blackberry/twitter-profile-analyzer by name.
• LangChain / LlamaIndex: use the Apify actor tool wrappers with the same actor id and input.
• Webhooks: configure an Apify webhook to fire on run completion (ACTOR.RUN.SUCCEEDED/FAILED) to push profile rows into your pipeline without polling.

Pricing

$0.05 start + $0.01 per profile result delivered (PAY_PER_EVENT). A 10-profile competitive scan costs about $0.15.

FAQ

Q: Can I track accounts over time? A: Yes — run recurring analyses on a schedule and diff the dataset rows to track follower growth, bio changes, and posting velocity over time.

Q: What about deleted, suspended, or private accounts? A: Unavailable profiles return a failure row with statusCode: 404 and ok: false, so agents can classify them without extra requests. Protected accounts still return public profile metadata.

Q: Do I need Twitter/X credentials? A: No. The actor resolves public profile data without login, cookies, or API keys.

Changelog

2026-08-15

• Rebuilt extraction engine: rows now include full profile metrics — followers, following, tweets, likes, bio, verified, joinDate, avatarUrl, website, location, name — plus derived audienceTier and followerRatio.
• Not-found profiles now return a clean statusCode: 404 failure row.
• Added 30-second request timeouts; per-item dataset pushes.
• Richer dataset overview view with avatar thumbnails and follower columns.

2026-08-14

• The required usernames input is now consumed — handles resolve to canonical profiles; added handles/username aliases.
• Added retry with exponential backoff on HTTP 429/5xx and network errors.
• Fail-loud runs: exit code 1 on invalid input or total failure; SUMMARY key-value record with failure aggregation.
• Published dataset output schema and agent/MCP integration docs.