> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scraperize.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Tweet
> Fetches a public tweet by its permalink and returns the focal tweet plus its reply thread. Set `trim=true` for a lightweight response.
**Cost: 1 credit** per successful request. Errors and cache hits (`cache_max_age`) are free.
Paste this into ChatGPT, Claude or your coding assistant to generate working code for this endpoint (use the copy button).
```text Prompt
I want to make an API call to /v1/twitter/tweet. Here are the details:
Endpoint: GET https://api.scraperize.com/v1/twitter/tweet
Description: Fetches a public tweet by its permalink and returns the focal tweet plus its reply thread. Set `trim=true` for a lightweight response.
Required Headers:
- x-api-key: Your API key
Parameters:
- url (string) [required]: Public tweet permalink, e.g. https://x.com/user/status/1234567890
- trim (select): Return a trimmed-down response: only the focal tweet with essential fields, and no reply thread (`replies`/`replyCount` are omitted).
- cache_max_age (select): Optional. Return a cached result if one this age or newer exists — served for **0 credits** with `meta.cached=true` and `meta.cachedAt`. Otherwise a fresh scrape runs (**1 credit**) and refreshes the cache. Omit to always scrape fresh.
Example Response:
{
"data": {
"focalTweet": {
"id": "2092616549722968274",
"url": "https://x.com/honour_can_code/status/2092616549722968274",
"text": "Global talent meets Global market \nand realized they cannot compete\n\nnow they’re back to local market",
"isLongForm": false,
"lang": "en",
"createdAtMs": 1787753639000,
"createdAt": "2026-08-26T14:13:59.000Z",
"counts": {
"likes": 1888,
"retweets": 361,
"replies": 83,
"quotes": 55,
"bookmarks": 81
},
"views": "111232",
"author": {
"id": "1551091092468162560",
"name": "Robinson Honour",
"screenName": "honour_can_code",
"url": "https://x.com/honour_can_code",
"bio": "building @pxxl_space",
"avatarUrl": "https://pbs.twimg.com/profile_images/1930817536863375361/OWkQS_oM_normal.jpg",
"avatarUrlHd": "https://pbs.twimg.com/profile_images/1930817536863375361/OWkQS_oM_400x400.jpg",
"followers": 13121,
"following": 1930,
"tweetCount": 16262,
"verified": true,
"protected": false,
"profileImageShape": "Circle",
"professionalCategory": null
},
"media": [],
"mentions": [],
"urls": [],
"hashtags": [],
"cashtags": [],
"card": null,
"communityNote": null,
"article": null,
"isReply": false,
"replyToTweetId": null,
"replyToUserId": null,
"isQuote": false,
"quotedTweetId": null,
"quotedTweet": null,
"conversationControl": null,
"editTweetIds": [
"2092616549722968274"
],
"place": null
},
"replies": [
{
"id": "2092648660848783643",
"url": "https://x.com/jayhemz/status/2092648660848783643",
"text": "@honour_can_code I go lie for you?",
"isLongForm": false,
"lang": "en",
"createdAtMs": 1787761294000,
"createdAt": "2026-08-26T16:21:34.000Z",
"counts": {
"likes": 85,
"retweets": 2,
"replies": 6,
"quotes": 0,
"bookmarks": 1
},
"views": "6566",
"author": {
"id": "1625981691058704384",
"name": "Johnmark Obiefuna",
"screenName": "jayhemz",
"url": "https://x.com/jayhemz",
"bio": null,
"avatarUrl": "https://pbs.twimg.com/profile_images/2062452288128442368/mEjipPZ9_normal.jpg",
"avatarUrlHd": "https://pbs.twimg.com/profile_images/2062452288128442368/mEjipPZ9_400x400.jpg",
"followers": 11876,
"following": 2746,
"tweetCount": 17000,
"verified": true,
"protected": false,
"profileImageShape": "Circle",
"professionalCategory": null
},
"media": [],
"mentions": [
{
"screenName": "honour_can_code",
"id": "1551091092468162560",
"indices": [
0
]
}
],
"urls": [],
"hashtags": [],
"cashtags": [],
"card": null,
"communityNote": null,
"article": null,
"isReply": true,
"replyToTweetId": "2092616549722968274",
"replyToUserId": "1551091092468162560",
"isQuote": false,
"quotedTweetId": null,
"quotedTweet": null,
"conversationControl": null,
"editTweetIds": [
"2092648660848783643"
],
"place": null
}
],
"replyCount": 3,
"fetchedAt": "2026-10-05T14:42:24.932Z"
},
"meta": {
"requestId": "req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f",
"creditsCharged": 1,
"creditsRemaining": 4999,
"cached": false
}
}
Please help me write code in my preferred programming language to make this API call and handle the response appropriately. Include error handling and best practices.
```
## OpenAPI
````yaml /api-reference/openapi.json get /v1/twitter/tweet
openapi: 3.0.3
info:
title: Scraperize API
version: 1.0.0
description: >-
Extract public data from social media platforms as clean JSON. Endpoints are
split by platform and by what they return, e.g. `GET /v1/twitter/tweet`.
## Authentication
Send your API key in the `x-api-key` header (or `Authorization: Bearer
`). Create keys in your dashboard.
## Credits
Each successful live scrape costs **1 credit**. Credits are prepaid and
never expire.
## Caching
Every endpoint accepts an optional `cache_max_age`
(`1d`|`3d`|`7d`|`14d`|`30d`). A cache hit within that window is returned for
**0 credits**.
## Responses
Success returns `{ "data": …, "meta": { "requestId", … } }`. Errors return
`{ "error": { "code", "message", "requestId" } }` with a matching HTTP
status. `meta` on a scrape carries `creditsCharged`, `creditsRemaining`,
`cached`, and (on a hit) `cachedAt`.
## Rate limits
Requests are limited per team per minute; over the limit returns `429` with
a `Retry-After` header.
servers:
- url: https://api.scraperize.com
description: Production
security:
- ApiKeyAuth: []
tags:
- name: Twitter
description: Twitter / X scraping endpoints
- name: Facebook
description: Facebook scraping endpoints
- name: Linkme
description: Linkme (link.me) scraping endpoints
- name: Amazon
description: Amazon (creator shop / storefront) scraping endpoints
- name: Linkbio
description: Linkbio (lnk.bio) scraping endpoints
- name: Pillar
description: Pillar (pillar.io) scraping endpoints
- name: Komi
description: Komi (komi.io) scraping endpoints
- name: Linktree
description: Linktree (linktr.ee) scraping endpoints
- name: Kick
description: Kick (kick.com) scraping endpoints
- name: Snapchat
description: Snapchat (snapchat.com) scraping endpoints
- name: Telegram
description: Telegram (t.me) scraping endpoints
- name: LinkedIn
description: LinkedIn scraping endpoints
- name: Twitch
description: Twitch scraping endpoints
- name: TikTok
description: TikTok (tiktok.com) scraping endpoints
paths:
/v1/twitter/tweet:
get:
tags:
- Twitter
summary: Tweet
description: >-
Fetches a public tweet by its permalink and returns the focal tweet plus
its reply thread. Set `trim=true` for a lightweight response.
parameters:
- name: url
in: query
required: true
description: Public tweet permalink, e.g. https://x.com/user/status/1234567890
schema:
type: string
example: https://x.com/honour_can_code/status/2092616549722968274
- name: trim
in: query
required: false
description: >-
Return a trimmed-down response: only the focal tweet with essential
fields, and no reply thread (`replies`/`replyCount` are omitted).
schema:
type: boolean
default: false
- name: cache_max_age
in: query
required: false
description: >-
Optional. Return a cached result if one this age or newer exists —
served for **0 credits** with `meta.cached=true` and
`meta.cachedAt`. Otherwise a fresh scrape runs (**1 credit**) and
refreshes the cache. Omit to always scrape fresh.
schema:
type: string
enum:
- 1d
- 3d
- 7d
- 14d
- 30d
example: 7d
responses:
'200':
description: The focal tweet and its replies.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
focalTweet:
type: object
nullable: true
replies:
type: array
items:
type: object
replyCount:
type: integer
fetchedAt:
type: string
format: date-time
meta:
type: object
description: >-
requestId + credit/caching metadata (creditsCharged,
creditsRemaining, cached, cachedAt).
required:
- data
- meta
example:
data:
focalTweet:
id: '2092616549722968274'
url: https://x.com/honour_can_code/status/2092616549722968274
text: |-
Global talent meets Global market
and realized they cannot compete
now they’re back to local market
isLongForm: false
lang: en
createdAtMs: 1787753639000
createdAt: '2026-08-26T14:13:59.000Z'
counts:
likes: 1888
retweets: 361
replies: 83
quotes: 55
bookmarks: 81
views: '111232'
author:
id: '1551091092468162560'
name: Robinson Honour
screenName: honour_can_code
url: https://x.com/honour_can_code
bio: building @pxxl_space
avatarUrl: >-
https://pbs.twimg.com/profile_images/1930817536863375361/OWkQS_oM_normal.jpg
avatarUrlHd: >-
https://pbs.twimg.com/profile_images/1930817536863375361/OWkQS_oM_400x400.jpg
followers: 13121
following: 1930
tweetCount: 16262
verified: true
protected: false
profileImageShape: Circle
professionalCategory: null
media: []
mentions: []
urls: []
hashtags: []
cashtags: []
card: null
communityNote: null
article: null
isReply: false
replyToTweetId: null
replyToUserId: null
isQuote: false
quotedTweetId: null
quotedTweet: null
conversationControl: null
editTweetIds:
- '2092616549722968274'
place: null
replies:
- id: '2092648660848783643'
url: https://x.com/jayhemz/status/2092648660848783643
text: '@honour_can_code I go lie for you?'
isLongForm: false
lang: en
createdAtMs: 1787761294000
createdAt: '2026-08-26T16:21:34.000Z'
counts:
likes: 85
retweets: 2
replies: 6
quotes: 0
bookmarks: 1
views: '6566'
author:
id: '1625981691058704384'
name: Johnmark Obiefuna
screenName: jayhemz
url: https://x.com/jayhemz
bio: null
avatarUrl: >-
https://pbs.twimg.com/profile_images/2062452288128442368/mEjipPZ9_normal.jpg
avatarUrlHd: >-
https://pbs.twimg.com/profile_images/2062452288128442368/mEjipPZ9_400x400.jpg
followers: 11876
following: 2746
tweetCount: 17000
verified: true
protected: false
profileImageShape: Circle
professionalCategory: null
media: []
mentions:
- screenName: honour_can_code
id: '1551091092468162560'
indices:
- 0
- 16
urls: []
hashtags: []
cashtags: []
card: null
communityNote: null
article: null
isReply: true
replyToTweetId: '2092616549722968274'
replyToUserId: '1551091092468162560'
isQuote: false
quotedTweetId: null
quotedTweet: null
conversationControl: null
editTweetIds:
- '2092648660848783643'
place: null
- id: '2092623785853632573'
url: https://x.com/dili369_/status/2092623785853632573
text: >-
@honour_can_code The unstoppable force met the moveable
object
isLongForm: false
lang: en
createdAtMs: 1787755364000
createdAt: '2026-08-26T14:42:44.000Z'
counts:
likes: 31
retweets: 0
replies: 1
quotes: 0
bookmarks: 0
views: '3332'
author:
id: '1700457183807205376'
name: DILI
screenName: dili369_
url: https://x.com/dili369_
bio: null
avatarUrl: >-
https://pbs.twimg.com/profile_images/2097802899275546624/HoSifLls_normal.jpg
avatarUrlHd: >-
https://pbs.twimg.com/profile_images/2097802899275546624/HoSifLls_400x400.jpg
followers: 2324
following: 1932
tweetCount: 22668
verified: false
protected: false
profileImageShape: Circle
professionalCategory: null
media: []
mentions:
- screenName: honour_can_code
id: '1551091092468162560'
indices:
- 0
- 16
urls: []
hashtags: []
cashtags: []
card: null
communityNote: null
article: null
isReply: true
replyToTweetId: '2092616549722968274'
replyToUserId: '1551091092468162560'
isQuote: false
quotedTweetId: null
quotedTweet: null
conversationControl: null
editTweetIds:
- '2092623785853632573'
place: null
- id: '2092662184731975716'
url: https://x.com/agentm2021/status/2092662184731975716
text: >-
@honour_can_code The CEOs with god complexes who believe
they're world class geniuses shackled by the average
Naija employee.
Funny people
isLongForm: false
lang: en
createdAtMs: 1787764519000
createdAt: '2026-08-26T17:15:19.000Z'
counts:
likes: 24
retweets: 0
replies: 0
quotes: 0
bookmarks: 0
views: '1742'
author:
id: '1300178055856558080'
name: splintercell
screenName: agentm2021
url: https://x.com/agentm2021
bio: null
avatarUrl: >-
https://pbs.twimg.com/profile_images/1387517169345437696/G8BcGg0O_normal.jpg
avatarUrlHd: >-
https://pbs.twimg.com/profile_images/1387517169345437696/G8BcGg0O_400x400.jpg
followers: 93
following: 111
tweetCount: 25677
verified: false
protected: false
profileImageShape: Circle
professionalCategory: null
media: []
mentions:
- screenName: honour_can_code
id: '1551091092468162560'
indices:
- 0
- 16
urls: []
hashtags: []
cashtags: []
card: null
communityNote: null
article: null
isReply: true
replyToTweetId: '2092616549722968274'
replyToUserId: '1551091092468162560'
isQuote: false
quotedTweetId: null
quotedTweet: null
conversationControl: null
editTweetIds:
- '2092662184731975716'
place: null
replyCount: 3
fetchedAt: '2026-10-05T14:42:24.932Z'
meta:
requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f
creditsCharged: 1
creditsRemaining: 4999
cached: false
'401':
description: Missing, invalid, or revoked API key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: UNAUTHORIZED
message: API key required — pass it in the `x-api-key` header.
requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f
'402':
description: Not enough credits for this request.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: INSUFFICIENT_CREDITS
message: >-
This request costs 1 credit, but your balance is 0. Top up
to continue.
requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f
'422':
description: Invalid query parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: VALIDATION_ERROR
message: Request validation failed
requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f
details:
- path: url
message: Required
'429':
description: Over the per-minute rate limit — honour `Retry-After`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: RATE_LIMITED
message: >-
Rate limit exceeded — max 100 requests per 60s. Retry in
~30s.
requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f
'503':
description: >-
Temporarily unavailable — retry after `Retry-After`. `error.code`
tells you why: `UPSTREAM_BLOCKED` (the source blocked this request),
`EXTRACTION_FAILED` (the source returned unexpected data),
`PLATFORM_UNAVAILABLE` (the source is down), or
`SERVICE_UNAVAILABLE` (we are at capacity).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: UPSTREAM_BLOCKED
message: >-
The source is temporarily unavailable. Please try again
shortly.
requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f
components:
schemas:
Error:
type: object
properties:
error:
type: object
properties:
code:
type: string
example: NOT_FOUND
message:
type: string
example: The requested content was not found.
requestId:
type: string
example: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f
details:
type: array
items:
type: object
description: Present on validation errors.
required:
- code
- message
- requestId
required:
- error
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: >-
Your API key. Send it in the `x-api-key` header (or `Authorization:
Bearer `). Create and manage keys from your dashboard.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.