WEB DATA

Twitter user timeline

Retrieve public posts and profile details from one Twitter account.

POSThttps://api.sukidata.com/v1/twitter

QUICKSTART

Make a request

Identify the account by username or numeric user ID. The default page contains up to 20 posts.

cURL

curl --request POST \
  --url https://api.sukidata.com/v1/twitter \
  --header "Authorization: Bearer $SUKIDATA_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "username": "Cloudflare",
    "max_results": 20
  }'

Try it in the Playground →

REQUEST BODY

Parameters

Provide exactly one of username or user_id.

usernamestring · one required

Twitter username with or without a leading @.

user_idstring · one required

Numeric Twitter user ID.

max_resultsinteger

Maximum posts returned in this page, from 1 to 100. The default is 20.

cursorstring

The opaque next_cursor value from the preceding response.

asyncboolean

Set to true to receive the search ID immediately and query the result later. Defaults to false.

View the complete Twitter schema in the API Reference

RESPONSE

Timeline result

A completed response contains the account, its posts, and a cursor when another page is available.

This illustrative response contains one post. Optional profile and engagement fields depend on what is available.

Example response

{
  "search_metadata": {
    "id": "twitter_example",
    "status": "Success",
    "created_at": "2026-09-22T00:00:00Z",
    "total_time_taken": 1.1
  },
  "search_parameters": {
    "engine": "twitter",
    "username": "Cloudflare",
    "max_results": 20
  },
  "user": {
    "id": "123456789",
    "username": "Cloudflare",
    "name": "Cloudflare"
  },
  "tweets": [
    {
      "id": "1234567890123456789",
      "text": "Example post content.",
      "created_at": "2026-09-21T09:00:00Z"
    }
  ],
  "next_cursor": "example_next_page_cursor"
}

search_metadataRequest status, identifiers, timing, and result file links.

search_parametersAccount identifier and page settings used.

userPublic profile fields for the requested account.

tweetsReturned public posts, including text and available engagement details.

next_cursorOpaque value used to request the next page.

Still processing?If search_metadata.status is Queued or Processing, use search_metadata.id with GET /v1/twitter/{search_id} until the status is Success or Error. This can happen after a synchronous wait ends, too. Do not submit the same page again to check progress.

Request the next page

Copy the preceding response's next_cursor into cursor, keeping the same account. Replace the example cursor below with your returned value; do not decode or construct it. Stop when next_cursor is absent. Each new page is a separate request.

cURL

curl --request POST \
  --url https://api.sukidata.com/v1/twitter \
  --header "Authorization: Bearer $SUKIDATA_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "username": "Cloudflare",
    "max_results": 20,
    "cursor": "example_next_page_cursor"
  }'

BILLING

Credit usage

Twitter uses Web Data credits. Read X-Sukidata-Credits-Used for the final charge. See Web Data billing for rates and free responses.

Need help with a request? Email support@sukidata.com and include the X-Request-ID response header.

Handle errors

400: provide exactly one account identifier and a max_results value from 1 to 100.
401: check your API key; 402: add Web Data credits.
503: the service is temporarily unavailable; wait before trying again.

An HTTP 200 response with search_metadata.status: Error is a failed search; read its error object. A Success response with an empty tweets array means this page has no available posts.