Live status

GET/v1/twitter/user/live1 credit

Tells whether an X account is broadcasting live right now, or the state of one broadcast or X Space: title, start time, current viewer or participant count and the URL while it runs. Our own endpoint: ScrapeCreators has no X live route.

01Query parameters

Name	Type	Description
handleoptional	string	The account's username, e.g. `GBNEWS`. A leading `@` is ignored. Required unless `url` is given.
urloptional	string	A broadcast link, `https://x.com/i/broadcasts/<id>` (twitter.com and periscope.tv links work too), or an X Space link, `https://x.com/i/spaces/<id>` (with or without `/peek`). Takes precedence over `handle`.

02Request

curl "https://api.scrapesocial.ai/v1/twitter/user/live?handle=GBNEWS" \
  -H "x-api-key: $SCRAPESOCIAL_KEY"

03Responses

Real answers from the API. Lists are shortened to 2 items.

GET /v1/twitter/user/live?handle=GBNEWS

{
  "success": true,
  "credits_remaining": 4980,
  "credits_charged": 1,
  "platform": "twitter",
  "is_live": true,
  "live_id": "1yoKMPeeqAdxQ",
  "title": "GB News",
  "started_at": "2026-10-25T12:59:57Z",
  "viewer_count": 2275,
  "url": "https://x.com/i/broadcasts/1yoKMPeeqAdxQ",
  "owner": {
    "id": "1339166129110065152",
    "username": "GBNEWS",
    "display_name": "GB News"
  }
}

Common to every endpoint

Any route can answer these: a missing or wrong key, no credits left, the platform not answering, or a failure on our side. None of them costs credits.

GET /v1/cosmos/profile?handle=design

{
  "success": false,
  "message": "Invalid API key"
}

04Notes

The answer is `platform, is_live, live_id, title, started_at, viewer_count, url, owner{id, username, display_name}`. Live or not, the answer costs 1 credit; when not live the stream fields are null (for a `url`, `live_id` is the asked broadcast). By handle the status is read from the account's newest posts, which carry a card for every live broadcast: a broadcast announced without a post, or one whose post is not among the newest (about 20; the largest accounts' top posts), is not seen. `viewer_count` is X's own "watching" figure; for a Space it is the number of people in it right now (hosts, speakers and listeners), not the running total of everyone who listened. A Space is read only by its link, never by handle. An unknown account, broadcast or Space answers 404, an account with protected posts 403, a value that is not a handle, a broadcast link or a Space link 400, all free.

05Errors & credits

Every error has success: false, a real HTTP status and costs no credits.

400missing_parameter
A required parameter is missing or invalid.
403private_account
The account is private or age-restricted.
404not_found
No such account.
503upstream_error
The platform did not answer; retry shortly.