Tutorial · curl
How to scrape X (Twitter) profiles with curl (2026)
A curl walkthrough for GET /v1/twitter/profiles/{handle}. Copy the snippet, run it, then read the JSON.
GET /v1/twitter/profiles/{handle} · 1 credit per successful request.
In this tutorial
You'll pull a public X (Twitter) profile and see the fields you get back.
Example job: refresh a creator roster from X (Twitter) handles you already have.
Step 1
Get ready
You need a Social Fetch API key and a working curl environment. New accounts include 100 free credits.
API key. Create a Social Fetch account and copy an API key. New accounts include 100 free credits.
curl setup. Any shell with curl. Export SOCIALFETCH_API_KEY before you run the sample.
When you're done, SOCIALFETCH_API_KEY is set in your shell.
Step 2
Make the request
Copy the curl snippet, keep SOCIALFETCH_API_KEY in the environment, and send GET /v1/twitter/profiles/{handle} with the x-api-key header. Example path: /v1/twitter/profiles/elonmusk. The sample uses public values for profiles.
You should see a JSON body on stdout. Use curl -sS so HTTP errors still print on stderr.
Step 3
Read the response
A JSON body with data (the profiles) and meta (creditsCharged, requestId). The sample below is illustrative; field-level docs live on the endpoint page. Credits charge on completed lookups, not transport failures.
Branch on data.lookupStatus when present, then keep meta.requestId if a row looks wrong.
Watch out
profile lookup is not a timeline. A missing or suspended handle should stop the pipeline before you burn credits on /profiles/{handle}/tweets. Branch on lookupStatus the same way you would for Instagram or TikTok profile cards.
Step 4
You finished
Same path and credits in playground, docs, and production. Pick a next action below.
FAQ
Common questions
Do I need an official X (Twitter) developer account?
No. Social Fetch authenticates with your Social Fetch API key. You call GET /v1/twitter/profiles/{handle} and we handle upstream access. You still need to follow each platform's terms for how you use public data.
What does the x (twitter) profiles endpoint return?
A JSON envelope with data (the profiles) and meta (creditsCharged, requestId). Shape details and field docs live on the endpoint page and in the OpenAPI docs.
Is an X profile lookup the same as listing that user's tweets?
No. This endpoint returns the profile card only. To list posts for a handle, use GET /v1/twitter/profiles/{handle}/tweets — a separate operation with its own credit note.
Do I need an X developer app or Bearer token for profile lookup?
No. Authenticate to Social Fetch with x-api-key only. You still need to follow X's terms for how you use public data after you receive it.
How much does a successful request cost?
1 credit per successful request.
Is this okay for production?
Yes. Same production API as the rest of Social Fetch: typed errors, requestId on every response, and credit charges only on completed lookups (not infrastructure failures). New accounts get 100 free credits.
Any curl-specific tips for this request?
Yes. Pass the key with -H "x-api-key: $SOCIALFETCH_API_KEY", and wrap the full URL in double quotes so the shell does not split on & in query strings. Prefer curl -sS so HTTP errors still surface on stderr.
Related