---
title: "Search X (formerly Twitter)"
method: GET
path: "/v1/x/search"
---

# Search X (formerly Twitter)

`GET /v1/x/search`

## Request

- Base URL: `https://api.veezee.io`
- URL: `https://api.veezee.io/v1/x/search`
- Auth: HTTP bearer

Search X by keywords. type picks the mode: recent (default) is the deep chronological sweep and keeps paginating as far as you follow the cursor; popular returns the highest-engagement tweets for the query; people finds accounts and returns a single page (no cursor). Advanced query operators pass through verbatim, e.g. "from:nasa", "min_faves:100", exact phrases in quotes -- there is no separate date parameter, so use since:/until: operators for time windows. Costs 6 credits per page; a cursor page is a NEW call priced the same way, so a deep sweep costs linearly in pages. Returns tweet summaries (text, author with follower count, views, likes, retweets, replies, created_at, url, id) with a cursor. Fetch one tweet's full detail with x_get_tweet and an account's timeline with x_get_tweets. For comment-level sentiment inside topic communities, reddit_search type=comments is usually the sharper instrument.

## Query parameters

- `query` string, required: Free-text keywords; X advanced operators work, e.g. 'claude code from:AnthropicAI since:2026-06-01'.
- `type` 'recent' | 'popular' | 'people': recent = chronological deep sweep; popular = top engagement; people = account search (single page).
- `cursor` string: Cursor from a previous page. Not valid with type 'people'.
- `freshness` 'recent' | 'realtime': recent (default) serves cached data from the last few hours when available; realtime forces a live fetch for +2 credits (refunded if we fall back to cached data). Trial keys are cached-only and reject realtime with TRIAL_CAP_EXCEEDED; paying upgrades this same key to unlock it.
- `max_credits` integer: Spend ceiling for this one call. The call is rejected (nothing charged) if its quote exceeds this. Only the quote is ever reserved, never this ceiling.

## Headers

- `Idempotency-Key` string

## Response `200`

x_search envelope (schema_version 2)

- XSearchEnvelope
  - `entity` 'x_search', required
  - `platform` 'linkedin' | 'reddit' | 'x', nullable, required
  - `canonical_url` string, nullable, required
  - `data_as_of` string, nullable, required
  - `schema_version` '2', required
  - `common` object, required
    - `type` 'recent' | 'popular' | 'people', required: Which result array is populated.
    - `tweets` object[], nullable, required
      - `id` string, required: Numeric tweet id as a string. Pass to x_get_tweet.
      - `text` string, nullable, required
      - `author` object, nullable, required
        - `screen_name` string, nullable, required: Handle without the @, e.g. 'nasa'.
        - `name` string, nullable, required
        - `id` string, nullable, required: Numeric account id as a string; stable across handle changes.
        - `followers` integer, nullable, required
        - `is_verified` boolean, nullable, required: Blue-check state.
      - `created_at` string, nullable, required: ISO 8601.
      - `url` string, nullable, required: Canonical x.com URL.
      - `views` integer, nullable, required
      - `likes` integer, nullable, required
      - `retweets` integer, nullable, required
      - `replies` integer, nullable, required
      - `quotes` integer, nullable, required
      - `bookmarks` integer, nullable, required
      - `lang` string, nullable, required
      - `is_reply` boolean, nullable, required
      - `is_retweet` boolean, nullable, required
      - `is_quote` boolean, nullable, required
      - `in_reply_to_screen_name` string, nullable, required
      - `conversation_id` string, nullable, required: Thread root tweet id; equal to id for thread starters.
      - `possibly_sensitive` boolean, nullable, required
    - `people` object[], nullable, required
      - `screen_name` string, nullable, required: Handle without the @, e.g. 'nasa'.
      - `name` string, nullable, required
      - `id` string, nullable, required: Numeric account id as a string; stable across handle changes.
      - `followers` integer, nullable, required
      - `is_verified` boolean, nullable, required: Blue-check state.
      - `description` string, nullable, required
      - `location` string, nullable, required
    - `cursor` string, nullable, required: Pass back to fetch the next page. Null when exhausted or for type 'people' (single page).
    - `next_url` string, nullable, required
    - `returned_count` integer, required
    - `truncation_hint` string, nullable, required: Present when results were cut off; says how to narrow or continue.
  - `platform_fields` object, required
  - `freshness` object, nullable, required
    - `source_retrieved_at` string, nullable, required: When the data was fetched from the source. ISO 8601.
    - `served_at` string, required
    - `cache_age_seconds` integer, nullable, required
    - `served_from_cache` boolean, required: True when these bytes were served from cache rather than fetched for this call. source_retrieved_at says how old they are.
    - `freshness_requested` 'recent' | 'realtime', required
    - `freshness_served` 'recent' | 'realtime' | 'stale', required
  - `usage` object, required
    - `receipt_id` string, nullable, required
    - `credits_quoted` integer, required
    - `credits_charged` integer, required
    - `balance_remaining` integer, nullable, required
    - `free_tier_hint` string: Present on free-tier trial-key calls: what budget the call drew from and that paying upgrades this same key. Near the daily cap on unclaimed keys it also carries a claim link to relay to your human (claiming adds one-time credits).

## Other responses

- `400`: INVALID_INPUT | IDEMPOTENCY_KEY_REQUIRED
- `401`: UNAUTHORIZED | AUTH_REQUIRED | KEY_REQUIRED
- `402`: INSUFFICIENT_CREDITS | QUOTE_EXCEEDS_MAX_CREDITS
- `403`: NOT_ENTITLED | TRIAL_CAP_EXCEEDED
- `404`: NOT_FOUND
- `409`: IDEMPOTENCY_KEY_REUSED
- `413`: PAYLOAD_TOO_LARGE
- `429`: CONCURRENCY_LIMIT | RATE_LIMITED
- `500`: INTERNAL
- `502`: UPSTREAM_UNAVAILABLE
- `503`: BUDGET_EXHAUSTED

---

[API](https://skmtc.dev/veezee/apis/veezee-api.md) · [All operations](https://skmtc.dev/veezee/apis/veezee-api/llms.txt) · [OpenAPI document](https://skmtc.dev/veezee/apis/veezee-api/revisions/6f1831474e70?raw)