---
title: "Advanced search"
method: GET
path: "/v1/tweets/search"
tags: ["tweets"]
---

# Advanced search

`GET /v1/tweets/search`

## Request

- Base URL: `https://api.xdataapi.io`
- URL: `https://api.xdataapi.io/v1/tweets/search`
- Auth: one of:
  - API key in header `x-api-key`
  - OAuth 2 (authorization code, authorization URL `https://xdataapi.io/oauth/authorize`, token URL `https://xdataapi.io/api/oauth/token`, scopes: `read`)

1 credit per tweet, or per profile with `product=People` (then `data` is a list of User).
`q` accepts X advanced search operators (from:, since:, until:, min_faves:, -filter:replies ...).
`product=Top` is not served to every reading session at X; when it is not, the response is HTTP 403
`product_unavailable` and nothing is charged. `Latest` is always available.

## Query parameters

- `q` string, required
- `product` 'Latest' | 'Top' | 'People' | 'Photos' | 'Videos'
- `count` integer
- `cursor` string
- `fresh` boolean

## Response `200`

OK

- TweetPage
  - `items` integer, required: Objects returned.
  - `credits_charged` number, required
  - `balance_remaining` number, required
  - `cache` 'miss' | 'hit' | 'bypass', required
  - `request_id` string, uuid, required
  - `next_cursor` string
  - `data` Tweet[]
    - `id` string, required
    - `text` string, required
    - `lang` string
    - `created_at` string, date-time, required
    - `author_id` string, required
    - `author` User
      - `id` string, required
      - `handle` string, required
      - `name` string, required
      - `bio` string
      - `location` string
      - `url` string
      - `avatar_url` string
      - `banner_url` string
      - `verified` boolean
      - `protected` boolean
      - `followers` integer, required
      - `following` integer, required
      - `tweets` integer, required
      - `likes` integer
      - `listed` integer
      - `created_at` string, date-time, required
      - `pinned_tweet_ids` string[]
    - `conversation_id` string
    - `in_reply_to_id` string
    - `in_reply_to_user_id` string
    - `quoted_id` string
    - `retweeted_id` string
    - `replies` integer
    - `retweets` integer
    - `likes` integer
    - `quotes` integer
    - `bookmarks` integer
    - `views` integer
    - `media` Media[]
      - `type` 'photo' | 'video' | 'animated_gif'
      - `url` string
      - `width` integer
      - `height` integer
    - `urls` string[]
    - `hashtags` string[]
    - `mentions` string[]
    - `is_retweet` boolean
    - `is_quote` boolean
    - `is_reply` boolean
    - `source` string

## Other responses

- `400`: The request itself is wrong: a bad parameter, cursor or body. Free.
- `401`: Missing or invalid key. Free.
- `402`: Balance is zero. Buy a pack. Free.
- `403`: X denied this read to the current session (error 37). Free.
- `429`: Per-account rate limit. Free. Retry after `Retry-After` seconds.
- `500`: A fault on our side. Free. Quote `request_id` if it persists.
- `503`: Upstream failure. Free. Retry after `Retry-After` seconds.

---

[API](https://skmtc.dev/xdataapi/apis/xdataapi-io-api.md) · [All operations](https://skmtc.dev/xdataapi/apis/xdataapi-io-api/llms.txt) · [OpenAPI document](https://skmtc.dev/xdataapi/apis/xdataapi-io-api/revisions/90cd2c0db55a?raw)