---
title: "Tweets by id, batch"
method: POST
path: "/v1/tweets/batch"
tags: ["tweets"]
---

# Tweets by id, batch

`POST /v1/tweets/batch`

## Request

- Base URL: `https://api.xdataapi.io`
- URL: `https://api.xdataapi.io/v1/tweets/batch`
- 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`)

Up to 100 tweets in one call. 1 credit per tweet found; deleted or private tweets are listed in `errors`
and cost nothing. Results in input order. Also `GET /v1/tweets/batch?ids=20,21`.

## Query parameters

- `fresh` boolean

## Request body

- object
  - `ids` string[], required

## Response `200`

OK

- TweetBatch
  - `errors` BatchError[], required: Inputs that returned nothing, with the reason. Never charged.
    - `input` string, required: The handle or id as sent.
    - `code` 'not_found' | 'no_credits' | 'access_denied' | 'upstream_rate_limited' | 'no_account' | 'upstream_error' | 'request_rejected' | 'bad_request', required
    - `message` string, required
  - `items` integer, required: Objects returned.
  - `credits_charged` number, required
  - `balance_remaining` number, required
  - `cache` 'miss' | 'hit' | 'mixed' | 'bypass', required
  - `cache_hits` integer, required: Objects served from cache
  - `request_id` string, uuid, required
  - `data` Tweet[]: Found tweets
    - `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.
- `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)