BrowsableSend Authorization: Bearer YOUR_API_KEY. Get an API key →
Requires a connected x.com account. Browsable automatically uses a saved connection on your team when one is available.
If none is available, HTTP 428 includes a hosted_url. Complete sign-in there, then retry. Connect an account →
Parameters
Send these fields in a flat JSON body. Add _run to choose execution options.
querystringRequiredKeyword or phrase to search on X. Minimum length: 1. Maximum length: 2000.
limitintegerOptionalMaximum number of tweets to collect from the current search surface. Preferred name; max_tweets remains supported. Default: 100. Minimum: 1. Maximum: 500.
tabstringOptionalSearch tab to scrape. Default: "top". Allowed: "top", "latest", "people", "media", "lists".
Advanced & compatibility inputs 1
max_tweetsintegerOptionalMaximum number of tweets to collect from the current search surface. You can also use limit. Default: 100. Minimum: 1. Maximum: 500.
Response
Every response describes a run. Read result once run_status is succeeded.
run_id- The run to track. Keep it when contacting support.
run_status- Queued, running, waiting for sign-in, succeeded, or failed. Check this even after an HTTP 200.
status_url- Poll this URL while the run is pending. Keep the same run instead of starting another request.
result- The endpoint’s returned data. The example is illustrative; actual fields may be empty or unavailable.
error- On failure, inspect its code, message, retryable and action fields.
View the complete output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"success",
"query",
"tab",
"max_tweets_requested",
"count",
"tweets",
"pagination"
],
"properties": {
"tab": {
"enum": [
"top",
"latest",
"people",
"media",
"lists"
],
"type": "string"
},
"count": {
"type": "integer"
},
"query": {
"type": "string"
},
"tweets": {
"type": "array",
"items": {
"type": "object",
"required": [
"textContent",
"displayName",
"username",
"profilePhotoUrl",
"timestamp",
"tweetLink",
"isAd",
"numberOfReplies",
"numberOfRetweets",
"numberOfLikes",
"numberOfViews"
],
"properties": {
"isAd": {
"type": "boolean"
},
"username": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"timestamp": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"tweetLink": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"displayName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"textContent": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"numberOfLikes": {
"type": "integer"
},
"numberOfViews": {
"type": "integer"
},
"numberOfReplies": {
"type": "integer"
},
"profilePhotoUrl": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"numberOfRetweets": {
"type": "integer"
}
},
"additionalProperties": false
}
},
"success": {
"type": "boolean"
},
"pagination": {
"type": "object",
"required": [
"has_next_page",
"next_cursor"
],
"properties": {
"next_cursor": {
"type": "null"
},
"has_next_page": {
"type": "boolean"
}
},
"additionalProperties": false
},
"max_tweets_requested": {
"type": "integer"
}
},
"additionalProperties": false
}View a polled run response
{
"run_id": "00000000-0000-4000-8000-000000000001",
"task_key": "x-search",
"task_name": "X search",
"run_status": "succeeded",
"status_url": "/v1/runs/00000000-0000-4000-8000-000000000001",
"result": {
"tab": "top",
"count": 1,
"query": "London",
"tweets": [
{
"isAd": true,
"username": "Stylish Shoreditch Loft with Balcony",
"timestamp": "sample",
"tweetLink": "https://example.com/item-1",
"displayName": "Stylish Shoreditch Loft with Balcony",
"textContent": "Sample textcontent 1",
"numberOfLikes": 1,
"numberOfViews": 1,
"numberOfReplies": 1,
"profilePhotoUrl": "https://images.example.com/profilephotourl-1.jpg",
"numberOfRetweets": 1
}
],
"success": true,
"pagination": {
"next_cursor": null,
"has_next_page": true
},
"max_tweets_requested": 1
},
"error": null
}Errors & retries
400Fix the fields listed inerrorsbefore retrying.428Connect the requested website account using the returned sign-in link.429Wait for the duration inRetry-After.5xxRetry transient failures with backoff. Keep the request ID.
A failed run has its own error inside the response. Retry it only when error.retryable is true.
More examples
Async request with polling
RUN=$(curl -s -X POST "https://api-ingress-worker-staging.browsable-staging.workers.dev/v1/x/search" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"London"}')
RUN_ID=$(echo "$RUN" | jq -er '.run_id // empty') || { echo "$RUN" >&2; exit 1; }
POLL_DELAY=3
while true; do
RESULT=$(curl -s -H "Authorization: Bearer YOUR_API_KEY" "https://api-ingress-worker-staging.browsable-staging.workers.dev/v1/runs/$RUN_ID")
STATUS=$(echo "$RESULT" | jq -r '.run_status')
if [[ "$STATUS" =~ ^(succeeded|failed|errored|cancelled|canceled|expired)$ ]]; then
echo "$RESULT"
break
fi
sleep "$(awk "BEGIN { print $POLL_DELAY * (0.9 + ($RANDOM % 21) / 100) }")"
POLL_DELAY=$((POLL_DELAY < 30 ? POLL_DELAY * 2 : 30))
[ "$POLL_DELAY" -gt 30 ] && POLL_DELAY=30
doneWait-for-results request
curl -X POST "https://api-ingress-worker-staging.browsable-staging.workers.dev/v1/x/search" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"London","_run":{"async":false}}'Canonical & compatibility routes
You can also send the same JSON body to /v1/tasks/x-search/runs.
Compatibility route: /v1/twitter/search.