Skip to content
X-Buddy
Tiếng Việt

API reference

Look up many posts or people

x_lookup — Look up to 50 posts (posts) or up to 50 people (people: @handles or #user_ids) at once; each item says found or why not (unavailable = deleted / suspended / protected).

Markdown version

x_lookup · Live read on X (creates a job)

Look up to 50 posts (posts) or up to 50 people (people: @handles or #user_ids) at once; each item says found or why not (unavailable = deleted / suspended / protected). Long lists may need job_get. Counts against Read per item.
REST POST /api/public/v1/accounts/{account}/reads/lookup
MCP tool x_lookup
Permission needed accounts.run — Owner, Manager, Operator
Scope group x:read
Group Live reads on X
Shown up front in profiles —

Input

Field Type Required Description
account string (1–100 chars) Yes The X account to use: its X-Buddy account_id (from account_list) or its @handle. Ambiguous names return candidates instead of guessing.
posts array of string (1–300 chars) (1–50 items) No Post ids or x.com status URLs.
people array of string (1–60 chars) (1–50 items) No @handles or #numeric_user_ids (not mixed).

Result

Creates a job for the X account's VPS. REST waits up to wait seconds (default 15, max 20): when done it returns 200 with the result, otherwise 202 with Location: /api/public/v1/jobs/{job_id}. The final status is succeeded, failed, cancelled or unknown.

Example

Call over REST

curl -X POST "https://reach-link-craft.lovable.app/api/public/v1/accounts/%40your_x_account/reads/lookup" \
  -H "Authorization: Bearer $XBUDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Call over MCP

{
  "method": "tools/call",
  "params": {
    "name": "x_lookup",
    "arguments": {
      "account": "@your_x_account"
    }
  }
}

Errors you may get

Code HTTP Retryable
unauthorized 401 No
key_expired 401 No
integration_revoked 401 No
connection_not_linked 403 No
integration_paused 403 No
workspace_integrations_paused 403 No
integration_authorization_lost 403 No
workspace_suspended 403 No
forbidden 403 No
invalid_input 422 No
rate_limited 429 Yes
internal 500 Yes
ambiguous_account 409 No
account_not_allowed 403 No
not_found 404 No
agent_too_old 422 No
unsupported_by_account 422 No

Back to all operations