> ## 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.
# User posts
> Fetches a public Truth Social account's posts ("Truths") by username or user id — newest first, 20 per page with a `cursor` for the next: its own posts, quotes and ReTruths (returned as the original post with `repostedBy`). Each post has its id, link, text, date, edit date, language, author, reply, ReTruth and like counts, images, videos and GIFs (file, preview, size, duration, alt text), the link preview card, poll, mentions, hashtags and links, the quoted post, reply info, and sensitive / spoiler / sponsored flags. Also returns the account. Replies are not included. Only publicly available data is returned.
**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/truthsocial/user/posts. Here are the details:
Endpoint: GET https://api.scraperize.com/v1/truthsocial/user/posts
Description: Fetches a public Truth Social account's posts ("Truths") by username or user id — newest first, 20 per page with a `cursor` for the next: its own posts, quotes and ReTruths (returned as the original post with `repostedBy`). Each post has its id, link, text, date, edit date, language, author, reply, ReTruth and like counts, images, videos and GIFs (file, preview, size, duration, alt text), the link preview card, poll, mentions, hashtags and links, the quoted post, reply info, and sensitive / spoiler / sponsored flags. Also returns the account. Replies are not included. Only publicly available data is returned.
Required Headers:
- x-api-key: Your API key
Parameters:
- handle (string): The Truth Social username, e.g. `realDonaldTrump` (an `@handle` or `truthsocial.com/@...` URL also works). Required unless `userId` is given.
- userId (string): The account's numeric id (the profile's `id`), e.g. `107780257626128497`. Required unless `handle` is given; used when both are.
- cursor (string): The `cursor` from the previous page, to get the next one.
- 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": {
"user": {
"id": "107780257626128497",
"handle": "realDonaldTrump",
"displayName": "Donald J. Trump",
"url": "https://truthsocial.com/@realDonaldTrump",
"bio": null,
"bioMentions": [],
"bioLinks": [],
"avatarUrl": "https://static-assets-1.truthsocial.com/tmtg:prime-ts-assets/accounts/avatars/107/780/257/626/128/497/original/454286ac07a6f6e6.jpeg",
"headerUrl": "https://static-assets-1.truthsocial.com/tmtg:prime-ts-assets/accounts/headers/107/780/257/626/128/497/original/ba3b910ba387bf4e.jpeg",
"website": "www.DonaldJTrump.com",
"websiteUrl": "https://www.DonaldJTrump.com",
"location": null,
"isVerified": true,
"isPremium": true,
"isPrivate": false,
"isBot": false,
"isGroup": false,
"isTvAccount": false,
"isDiscoverable": null,
"acceptsMessages": false,
"followerCount": 13124452,
"followingCount": 69,
"postCount": 37354,
"createdAt": "2022-02-11T16:16:57.705Z",
"lastPostDate": "2026-10-20",
"emojis": []
},
"posts": [
{
"id": "117471498052081961",
"url": "https://truthsocial.com/@realDonaldTrump/posts/117471498052081961",
"text": null,
"createdAt": "2026-10-20T05:06:49.635Z",
"editedAt": null,
"language": null,
"author": {
"id": "107780257626128497",
"handle": "realDonaldTrump",
"displayName": "Donald J. Trump",
"url": "https://truthsocial.com/@realDonaldTrump",
"avatarUrl": "https://static-assets-1.truthsocial.com/tmtg:prime-ts-assets/accounts/avatars/107/780/257/626/128/497/original/454286ac07a6f6e6.jpeg",
"isVerified": true,
"isPremium": true,
"followerCount": 13124452
},
"replyCount": 306,
"repostCount": 670,
"likeCount": 2287,
"media": [
{
"id": "117471495349125026",
"type": "image",
"url": "https://static-assets-1.truthsocial.com/tmtg:prime-ts-assets/media_attachments/files/117/471/495/349/125/026/original/ae6e35d7a56228d3.jpg",
"previewUrl": "https://static-assets-1.truthsocial.com/tmtg:prime-ts-assets/media_attachments/files/117/471/495/349/125/026/small/ae6e35d7a56228d3.jpg",
"width": 1241,
"height": 828,
"durationSeconds": null,
"altText": null
}
],
"card": null,
"poll": null,
"mentions": [
{
"id": "107780257626128497",
"handle": "realDonaldTrump",
"url": "https://truthsocial.com/@realDonaldTrump"
}
],
"hashtags": [],
"links": [],
"quotedPost": {
"id": "117471474650381574",
"url": "https://truthsocial.com/@realDonaldTrump/posts/117471474650381574",
"text": "Here are pictures of Trash Island for the Judge to study. This is just a small area, and better than some! President DONALD J. TRUMP",
"createdAt": "2026-10-20T05:00:52.553Z",
"editedAt": null,
"language": "en",
"author": {
"id": "107780257626128497",
"handle": "realDonaldTrump",
"displayName": "Donald J. Trump",
"url": "https://truthsocial.com/@realDonaldTrump",
"avatarUrl": "https://static-assets-1.truthsocial.com/tmtg:prime-ts-assets/accounts/avatars/107/780/257/626/128/497/original/454286ac07a6f6e6.jpeg",
"isVerified": true,
"isPremium": true,
"followerCount": 13124452
},
"replyCount": 105,
"repostCount": 579,
"likeCount": 2040,
"media": [
{
"id": "117471473460790499",
"type": "image",
"url": "https://static-assets-1.truthsocial.com/tmtg:prime-ts-assets/media_attachments/files/117/471/473/460/790/499/original/7f682840d161a8c8.jpg",
"previewUrl": "https://static-assets-1.truthsocial.com/tmtg:prime-ts-assets/media_attachments/files/117/471/473/460/790/499/small/7f682840d161a8c8.jpg",
"width": 1009,
"height": 728,
"durationSeconds": null,
"altText": null
}
],
"card": null,
"poll": null,
"mentions": [
{
"id": "107780257626128497",
"handle": "realDonaldTrump",
"url": "https://truthsocial.com/@realDonaldTrump"
}
],
"hashtags": [],
"links": [],
"quotedPost": null,
"isReply": false,
"inReplyToPostId": null,
"inReplyToAccountId": null,
"isPinned": false,
"isSensitive": false,
"spoilerText": null,
"visibility": "public",
"isSponsored": false,
"repostedBy": null,
"repostedAt": null
},
"isReply": false,
"inReplyToPostId": null,
"inReplyToAccountId": null,
"isPinned": false,
"isSensitive": false,
"spoilerText": null,
"visibility": "public",
"isSponsored": false,
"repostedBy": null,
"repostedAt": null
}
],
"count": 20,
"cursor": "117471361607280244",
"hasMore": true,
"fetchedAt": "2026-10-20T10:07:26.203Z"
},
"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/truthsocial/user/posts
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
- name: Instagram
description: Instagram scraping endpoints
- name: Lagos Life
description: Lagos Life scraping endpoints
- name: Bluesky
description: Bluesky (bsky.app) scraping endpoints
- name: Threads
description: Threads (threads.com) scraping endpoints
- name: Truth Social
description: Truth Social (truthsocial.com) scraping endpoints
paths:
/v1/truthsocial/user/posts:
get:
tags:
- Truth Social
summary: User posts
description: >-
Fetches a public Truth Social account's posts ("Truths") by username or
user id — newest first, 20 per page with a `cursor` for the next: its
own posts, quotes and ReTruths (returned as the original post with
`repostedBy`). Each post has its id, link, text, date, edit date,
language, author, reply, ReTruth and like counts, images, videos and
GIFs (file, preview, size, duration, alt text), the link preview card,
poll, mentions, hashtags and links, the quoted post, reply info, and
sensitive / spoiler / sponsored flags. Also returns the account. Replies
are not included. Only publicly available data is returned.
parameters:
- name: handle
in: query
required: false
description: >-
The Truth Social username, e.g. `realDonaldTrump` (an `@handle` or
`truthsocial.com/@...` URL also works). Required unless `userId` is
given.
schema:
type: string
example: realDonaldTrump
- name: userId
in: query
required: false
description: >-
The account's numeric id (the profile's `id`), e.g.
`107780257626128497`. Required unless `handle` is given; used when
both are.
schema:
type: string
- name: cursor
in: query
required: false
description: The `cursor` from the previous page, to get the next one.
schema:
type: string
- 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 account and one page of its posts.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
user:
type: object
nullable: true
posts:
type: array
items:
type: object
count:
type: integer
cursor:
type: string
nullable: true
hasMore:
type: boolean
fetchedAt:
type: string
format: date-time
meta:
type: object
description: >-
requestId + credit/caching metadata (creditsCharged,
creditsRemaining, cached, cachedAt).
required:
- data
- meta
example:
data:
user:
id: '107780257626128497'
handle: realDonaldTrump
displayName: Donald J. Trump
url: https://truthsocial.com/@realDonaldTrump
bio: null
bioMentions: []
bioLinks: []
avatarUrl: >-
https://static-assets-1.truthsocial.com/tmtg:prime-ts-assets/accounts/avatars/107/780/257/626/128/497/original/454286ac07a6f6e6.jpeg
headerUrl: >-
https://static-assets-1.truthsocial.com/tmtg:prime-ts-assets/accounts/headers/107/780/257/626/128/497/original/ba3b910ba387bf4e.jpeg
website: www.DonaldJTrump.com
websiteUrl: https://www.DonaldJTrump.com
location: null
isVerified: true
isPremium: true
isPrivate: false
isBot: false
isGroup: false
isTvAccount: false
isDiscoverable: null
acceptsMessages: false
followerCount: 13124452
followingCount: 69
postCount: 37354
createdAt: '2022-02-11T16:16:57.705Z'
lastPostDate: '2026-10-20'
emojis: []
posts:
- id: '117471498052081961'
url: >-
https://truthsocial.com/@realDonaldTrump/posts/117471498052081961
text: null
createdAt: '2026-10-20T05:06:49.635Z'
editedAt: null
language: null
author:
id: '107780257626128497'
handle: realDonaldTrump
displayName: Donald J. Trump
url: https://truthsocial.com/@realDonaldTrump
avatarUrl: >-
https://static-assets-1.truthsocial.com/tmtg:prime-ts-assets/accounts/avatars/107/780/257/626/128/497/original/454286ac07a6f6e6.jpeg
isVerified: true
isPremium: true
followerCount: 13124452
replyCount: 306
repostCount: 670
likeCount: 2287
media:
- id: '117471495349125026'
type: image
url: >-
https://static-assets-1.truthsocial.com/tmtg:prime-ts-assets/media_attachments/files/117/471/495/349/125/026/original/ae6e35d7a56228d3.jpg
previewUrl: >-
https://static-assets-1.truthsocial.com/tmtg:prime-ts-assets/media_attachments/files/117/471/495/349/125/026/small/ae6e35d7a56228d3.jpg
width: 1241
height: 828
durationSeconds: null
altText: null
- id: '117471495350042172'
type: image
url: >-
https://static-assets-1.truthsocial.com/tmtg:prime-ts-assets/media_attachments/files/117/471/495/350/042/172/original/e4100d73ad01f476.jpg
previewUrl: >-
https://static-assets-1.truthsocial.com/tmtg:prime-ts-assets/media_attachments/files/117/471/495/350/042/172/small/e4100d73ad01f476.jpg
width: 1241
height: 828
durationSeconds: null
altText: null
- id: '117471495349957557'
type: image
url: >-
https://static-assets-1.truthsocial.com/tmtg:prime-ts-assets/media_attachments/files/117/471/495/349/957/557/original/360d5e57ac9bf090.jpg
previewUrl: >-
https://static-assets-1.truthsocial.com/tmtg:prime-ts-assets/media_attachments/files/117/471/495/349/957/557/small/360d5e57ac9bf090.jpg
width: 1241
height: 828
durationSeconds: null
altText: null
card: null
poll: null
mentions:
- id: '107780257626128497'
handle: realDonaldTrump
url: https://truthsocial.com/@realDonaldTrump
hashtags: []
links: []
quotedPost:
id: '117471474650381574'
url: >-
https://truthsocial.com/@realDonaldTrump/posts/117471474650381574
text: >-
Here are pictures of Trash Island for the Judge to
study. This is just a small area, and better than
some! President DONALD J. TRUMP
createdAt: '2026-10-20T05:00:52.553Z'
editedAt: null
language: en
author:
id: '107780257626128497'
handle: realDonaldTrump
displayName: Donald J. Trump
url: https://truthsocial.com/@realDonaldTrump
avatarUrl: >-
https://static-assets-1.truthsocial.com/tmtg:prime-ts-assets/accounts/avatars/107/780/257/626/128/497/original/454286ac07a6f6e6.jpeg
isVerified: true
isPremium: true
followerCount: 13124452
replyCount: 105
repostCount: 579
likeCount: 2040
media:
- id: '117471473460790499'
type: image
url: >-
https://static-assets-1.truthsocial.com/tmtg:prime-ts-assets/media_attachments/files/117/471/473/460/790/499/original/7f682840d161a8c8.jpg
previewUrl: >-
https://static-assets-1.truthsocial.com/tmtg:prime-ts-assets/media_attachments/files/117/471/473/460/790/499/small/7f682840d161a8c8.jpg
width: 1009
height: 728
durationSeconds: null
altText: null
- id: '117471473460879683'
type: image
url: >-
https://static-assets-1.truthsocial.com/tmtg:prime-ts-assets/media_attachments/files/117/471/473/460/879/683/original/ab7e317020030b41.jpg
previewUrl: >-
https://static-assets-1.truthsocial.com/tmtg:prime-ts-assets/media_attachments/files/117/471/473/460/879/683/small/ab7e317020030b41.jpg
width: 778
height: 680
durationSeconds: null
altText: null
- id: '117471473461095857'
type: image
url: >-
https://static-assets-1.truthsocial.com/tmtg:prime-ts-assets/media_attachments/files/117/471/473/461/095/857/original/d746e35bfd00fc70.jpg
previewUrl: >-
https://static-assets-1.truthsocial.com/tmtg:prime-ts-assets/media_attachments/files/117/471/473/461/095/857/small/d746e35bfd00fc70.jpg
width: 771
height: 795
durationSeconds: null
altText: null
card: null
poll: null
mentions:
- id: '107780257626128497'
handle: realDonaldTrump
url: https://truthsocial.com/@realDonaldTrump
hashtags: []
links: []
quotedPost: null
isReply: false
inReplyToPostId: null
inReplyToAccountId: null
isPinned: false
isSensitive: false
spoilerText: null
visibility: public
isSponsored: false
repostedBy: null
repostedAt: null
isReply: false
inReplyToPostId: null
inReplyToAccountId: null
isPinned: false
isSensitive: false
spoilerText: null
visibility: public
isSponsored: false
repostedBy: null
repostedAt: null
- id: '117471494164657339'
url: >-
https://truthsocial.com/@realDonaldTrump/posts/117471494164657339
text: >-
Collapsing Sea Wall — Very dangerous to one's health!
President DONALD J. TRUMP
createdAt: '2026-10-20T05:05:50.316Z'
editedAt: null
language: en
author:
id: '107780257626128497'
handle: realDonaldTrump
displayName: Donald J. Trump
url: https://truthsocial.com/@realDonaldTrump
avatarUrl: >-
https://static-assets-1.truthsocial.com/tmtg:prime-ts-assets/accounts/avatars/107/780/257/626/128/497/original/454286ac07a6f6e6.jpeg
isVerified: true
isPremium: true
followerCount: 13124452
replyCount: 143
repostCount: 637
likeCount: 2243
media:
- id: '117471492208190228'
type: image
url: >-
https://static-assets-1.truthsocial.com/tmtg:prime-ts-assets/media_attachments/files/117/471/492/208/190/228/original/e43fffb436d9b87e.jpg
previewUrl: >-
https://static-assets-1.truthsocial.com/tmtg:prime-ts-assets/media_attachments/files/117/471/492/208/190/228/small/e43fffb436d9b87e.jpg
width: 1170
height: 877
durationSeconds: null
altText: null
card: null
poll: null
mentions:
- id: '107780257626128497'
handle: realDonaldTrump
url: https://truthsocial.com/@realDonaldTrump
hashtags: []
links: []
quotedPost:
id: '117471491419200330'
url: >-
https://truthsocial.com/@realDonaldTrump/posts/117471491419200330
text: null
createdAt: '2026-10-20T05:05:08.425Z'
editedAt: null
language: null
author:
id: '107780257626128497'
handle: realDonaldTrump
displayName: Donald J. Trump
url: https://truthsocial.com/@realDonaldTrump
avatarUrl: >-
https://static-assets-1.truthsocial.com/tmtg:prime-ts-assets/accounts/avatars/107/780/257/626/128/497/original/454286ac07a6f6e6.jpeg
isVerified: true
isPremium: true
followerCount: 13124452
replyCount: 64
repostCount: 491
likeCount: 1920
media:
- id: '117471477603895759'
type: image
url: >-
https://static-assets-1.truthsocial.com/tmtg:prime-ts-assets/media_attachments/files/117/471/477/603/895/759/original/44826f4afe7fd60e.jpg
previewUrl: >-
https://static-assets-1.truthsocial.com/tmtg:prime-ts-assets/media_attachments/files/117/471/477/603/895/759/small/44826f4afe7fd60e.jpg
width: 1170
height: 877
durationSeconds: null
altText: null
- id: '117471477605436289'
type: image
url: >-
https://static-assets-1.truthsocial.com/tmtg:prime-ts-assets/media_attachments/files/117/471/477/605/436/289/original/3becc1025321f494.jpg
previewUrl: >-
https://static-assets-1.truthsocial.com/tmtg:prime-ts-assets/media_attachments/files/117/471/477/605/436/289/small/3becc1025321f494.jpg
width: 1170
height: 877
durationSeconds: null
altText: null
- id: '117471477604284696'
type: image
url: >-
https://static-assets-1.truthsocial.com/tmtg:prime-ts-assets/media_attachments/files/117/471/477/604/284/696/original/1ae7789210d8bb6e.jpg
previewUrl: >-
https://static-assets-1.truthsocial.com/tmtg:prime-ts-assets/media_attachments/files/117/471/477/604/284/696/small/1ae7789210d8bb6e.jpg
width: 1170
height: 877
durationSeconds: null
altText: null
card: null
poll: null
mentions: []
hashtags: []
links: []
quotedPost: null
isReply: false
inReplyToPostId: null
inReplyToAccountId: null
isPinned: false
isSensitive: false
spoilerText: null
visibility: public
isSponsored: false
repostedBy: null
repostedAt: null
isReply: false
inReplyToPostId: null
inReplyToAccountId: null
isPinned: false
isSensitive: false
spoilerText: null
visibility: public
isSponsored: false
repostedBy: null
repostedAt: null
- id: '117471491419200330'
url: >-
https://truthsocial.com/@realDonaldTrump/posts/117471491419200330
text: null
createdAt: '2026-10-20T05:05:08.425Z'
editedAt: null
language: null
author:
id: '107780257626128497'
handle: realDonaldTrump
displayName: Donald J. Trump
url: https://truthsocial.com/@realDonaldTrump
avatarUrl: >-
https://static-assets-1.truthsocial.com/tmtg:prime-ts-assets/accounts/avatars/107/780/257/626/128/497/original/454286ac07a6f6e6.jpeg
isVerified: true
isPremium: true
followerCount: 13124452
replyCount: 64
repostCount: 491
likeCount: 1920
media:
- id: '117471477603895759'
type: image
url: >-
https://static-assets-1.truthsocial.com/tmtg:prime-ts-assets/media_attachments/files/117/471/477/603/895/759/original/44826f4afe7fd60e.jpg
previewUrl: >-
https://static-assets-1.truthsocial.com/tmtg:prime-ts-assets/media_attachments/files/117/471/477/603/895/759/small/44826f4afe7fd60e.jpg
width: 1170
height: 877
durationSeconds: null
altText: null
- id: '117471477605436289'
type: image
url: >-
https://static-assets-1.truthsocial.com/tmtg:prime-ts-assets/media_attachments/files/117/471/477/605/436/289/original/3becc1025321f494.jpg
previewUrl: >-
https://static-assets-1.truthsocial.com/tmtg:prime-ts-assets/media_attachments/files/117/471/477/605/436/289/small/3becc1025321f494.jpg
width: 1170
height: 877
durationSeconds: null
altText: null
- id: '117471477604284696'
type: image
url: >-
https://static-assets-1.truthsocial.com/tmtg:prime-ts-assets/media_attachments/files/117/471/477/604/284/696/original/1ae7789210d8bb6e.jpg
previewUrl: >-
https://static-assets-1.truthsocial.com/tmtg:prime-ts-assets/media_attachments/files/117/471/477/604/284/696/small/1ae7789210d8bb6e.jpg
width: 1170
height: 877
durationSeconds: null
altText: null
card: null
poll: null
mentions: []
hashtags: []
links: []
quotedPost: null
isReply: false
inReplyToPostId: null
inReplyToAccountId: null
isPinned: false
isSensitive: false
spoilerText: null
visibility: public
isSponsored: false
repostedBy: null
repostedAt: null
count: 20
cursor: '117471361607280244'
hasMore: true
fetchedAt: '2026-10-20T10:07:26.203Z'
meta:
requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f
creditsCharged: 1
creditsRemaining: 4999
cached: false
'400':
description: Invalid or expired cursor.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: BAD_REQUEST
message: The request was invalid.
requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f
'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
'404':
description: No Truth Social account found for that handle or user id.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: NOT_FOUND
message: >-
The requested content was not found (it may not exist, be
deleted, or be private).
requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f
'422':
description: >-
Invalid query parameters (neither handle nor userId, or a malformed
one).
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: url is 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.