8 endpoints for public Threads data through one SocQ API key, with runnable cURL, Node.js and Python examples and a valid request body for every endpoint.
Browse Threads APIs · Get an API key · Documentation · All SocQ examples
Prices are in SocQ credits; 1 credit = $0.005.
| Endpoint | publicId | What it returns | Price | Launched |
|---|---|---|---|---|
| Threads Posts API | threads/posts |
Collect public Threads posts from supported post URLs, returning normalized text, author context, media, timestamps, and visible engagement metrics. | 0.5 credits ($0.0025) per result | 2026-07-19 |
| Threads Profiles API | threads/profiles |
Collect public Threads profiles from supported profile URLs, returning normalized identity, biographies, profile imagery, websites, visible account metrics, and collection context. | 0.6 credits ($0.003) per result | 2026-07-19 |
| Threads User Posts API | threads/user-posts |
Discover public Threads posts from supported profile URLs with a per-profile result limit, returning normalized content, author context, media, timestamps, visible engagement, and source context. | 0.5 credits ($0.0025) per result | 2026-07-19 |
| Threads Post Replies API | threads/post-replies |
Collect the replies under Threads posts with author, likes, replies, media and time. | 0.3 credits ($0.0015) per result | 2026-11-17 |
| Threads Search API | threads/search |
Search Threads posts by keyword or hashtag and get text, author, engagement and media. | 0.6 credits ($0.003) per result | 2026-11-17 |
| Threads User Search API | threads/search-users |
Find Threads accounts by name or username, with display name, avatar and verification status. | 0.6 credits ($0.003) per result | 2026-11-17 |
| Threads User Replies API | threads/user-replies |
Collect the latest public replies a Threads account has posted, with engagement and media. | 0.5 credits ($0.0025) per result | 2026-11-17 |
| Threads User Reposts API | threads/user-reposts |
Collect the posts a Threads account has reposted, each shown with its original author. | 0.5 credits ($0.0025) per result | 2026-11-17 |
- Create an API key at socq.ai/dashboard/api-key.
- Export it. The examples read only
SOCQ_API_KEY.
git clone https://github.com/SocQAPI/threads-api.git
cd threads-api
export SOCQ_API_KEY="your-api-key"- Run any endpoint by its publicId. Without a second argument the script sends
payloads/<slug>.json; pass a JSON file or an inline JSON object to change the input.
# Node.js 20+
node examples/node/socq.mjs threads/posts
# Python 3.8+ (standard library only)
python3 examples/python/socq.py threads/posts payloads/posts.json
# cURL + jq
bash examples/curl/socq.sh threads/posts '{"urls":["https://www.threads.com/@instagram/post/DbbbOW8D-T1"]}'Each script submits the task, polls it until it succeeds or fails, follows every result page, and writes the records to output/<slug>-<task_id>.json. Run npm run check to validate the payloads and scripts offline.
Never expose SOCQ_API_KEY in browser code, mobile apps, public repositories, screenshots, fixtures or logs.
Base URL https://api.socq.ai. Every request sends the API key as a bearer token:
Authorization: Bearer <SOCQ_API_KEY>
Content-Type: application/jsonAll endpoints are asynchronous:
POST /v1/<publicId> -> data.task_id -> GET /v1/tasks/{task_id} -> queued | running | succeeded | failed
- Submit the JSON body to
POST https://api.socq.ai/v1/<publicId>. The response returnsdata.task_idimmediately; it means the task was created, not that data is ready. - Poll
GET https://api.socq.ai/v1/tasks/{task_id}untildata.statusissucceededorfailed(a failed task carriesdata.error_message). - Read results. A succeeded task returns normalized records in
data.results.items. Uselimit(default 50, max 500) and passdata.results.next_cursorascursorwhiledata.results.has_moreis true.fieldsselects up to 50 comma-separated fields or dot paths. - Raw files (optional).
GET https://api.socq.ai/v1/tasks/{task_id}/fileslists raw JSONL exports.
curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=100" \
-H "Authorization: Bearer $SOCQ_API_KEY"
curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=100&cursor=$NEXT_CURSOR" \
-H "Authorization: Bearer $SOCQ_API_KEY"callback_url (where an endpoint accepts it) makes SocQ POST to your URL when the task reaches a terminal state; keep polling as a fallback.
Billing. A submit may reserve credits from results_limit or the number of submitted inputs; when the task finishes SocQ settles the charge from the actual result count and returns unused reserved credits. 402 means insufficient credits.
Errors. 400 invalid body or unsupported field, 401 missing or invalid key, 402 insufficient credits, 403 IP allowlist or task owned by another account, 404 endpoint or task not found, 422 input validation failed, 429 rate or credit-window limit (respect Retry-After), 500 submission failed. A client-side timeout does not cancel a task: resume polling the same task_id instead of submitting again.
Reference: Authentication · Task status and results · Task files · Callbacks · Errors
Collect public Threads posts from supported post URLs, returning normalized text, author context, media, timestamps, and visible engagement metrics.
- Request:
POST https://api.socq.ai/v1/threads/posts - publicId:
threads/posts - Price: 0.5 credits ($0.0025) per result
- Launched: 2026-07-19
- Example body:
payloads/posts.json
| Field | Type | Required | Description |
|---|---|---|---|
urls |
array of string | Yes | Public profile or content URLs. (items at least 1) |
curl -X POST "https://api.socq.ai/v1/threads/posts" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"urls": [
"https://www.threads.com/@instagram/post/DbbbOW8D-T1"
]
}'Full docs: https://docs.socq.ai/api-manual/threads/posts · Landing page: socq.ai/apis/threads/posts
Collect public Threads profiles from supported profile URLs, returning normalized identity, biographies, profile imagery, websites, visible account metrics, and collection context.
- Request:
POST https://api.socq.ai/v1/threads/profiles - publicId:
threads/profiles - Price: 0.6 credits ($0.003) per result
- Launched: 2026-07-19
- Example body:
payloads/profiles.json
| Field | Type | Required | Description |
|---|---|---|---|
urls |
array of string | Yes | Public profile or content URLs. (items at least 1) |
curl -X POST "https://api.socq.ai/v1/threads/profiles" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"urls": [
"https://www.threads.com/@example"
]
}'Full docs: https://docs.socq.ai/api-manual/threads/profiles · Landing page: socq.ai/apis/threads/profiles
Discover public Threads posts from supported profile URLs with a per-profile result limit, returning normalized content, author context, media, timestamps, visible engagement, and source context.
- Request:
POST https://api.socq.ai/v1/threads/user-posts - publicId:
threads/user-posts - Price: 0.5 credits ($0.0025) per result
- Launched: 2026-07-19
- Example body:
payloads/user-posts.json
| Field | Type | Required | Description |
|---|---|---|---|
results_limit |
integer | No | (value 1 to 2000) |
urls |
array of string | Yes | Public profile or content URLs. (items at least 1) |
curl -X POST "https://api.socq.ai/v1/threads/user-posts" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"urls": [
"https://www.threads.com/@example"
],
"results_limit": 100
}'Full docs: https://docs.socq.ai/api-manual/threads/user-posts · Landing page: socq.ai/apis/threads/user-posts
Collect the replies under Threads posts with author, likes, replies, media and time.
- Request:
POST https://api.socq.ai/v1/threads/post-replies - publicId:
threads/post-replies - Price: 0.3 credits ($0.0015) per result
- Launched: 2026-11-17
- Example body:
payloads/post-replies.json
Read the conversation under a Threads post. Each reply includes its text, author, like and reply counts, attached media and time, plus the ID of the post it answers. Use it to gauge reaction to an announcement, collect customer feedback from a brand's posts, or find the most engaged people in a creator's audience.
Provide Threads post URLs in urls, using /@{username}/post/{code}. Each post returns the replies Threads shows under it, around 20 per post. Each reply returned costs 0.3 credits.
| Field | Type | Required | Description |
|---|---|---|---|
callback_url |
string (uri) | No | - |
urls |
array of string | Yes | Public profile or content URLs. (items at least 1) |
curl -X POST "https://api.socq.ai/v1/threads/post-replies" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"urls": [
"https://www.threads.com/@unrivaledbasketball/post/Dfa88pLDs_1"
]
}'Full docs: https://docs.socq.ai/api-manual/threads/post-replies · Landing page: socq.ai/apis/threads/post-replies
Search Threads posts by keyword or hashtag and get text, author, engagement and media.
- Request:
POST https://api.socq.ai/v1/threads/search - publicId:
threads/search - Price: 0.6 credits ($0.003) per result
- Launched: 2026-11-17
- Example body:
payloads/search.json
Search Threads the way the app does and get the top posts for a keyword or hashtag. Every post comes with its text, author, likes, replies, reposts, media and publish time. It is the fastest way to see how a topic, product or event is being discussed on Threads, and to find the accounts driving that conversation.
Provide a keyword or hashtag in query. Each search returns the top posts Threads shows for it, about 20. Each post returned costs 0.6 credits.
| Field | Type | Required | Description |
|---|---|---|---|
callback_url |
string (uri) | No | - |
query |
string | Yes | Search query. |
curl -X POST "https://api.socq.ai/v1/threads/search" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "basketball"
}'Full docs: https://docs.socq.ai/api-manual/threads/search · Landing page: socq.ai/apis/threads/search
Find Threads accounts by name or username, with display name, avatar and verification status.
- Request:
POST https://api.socq.ai/v1/threads/search-users - publicId:
threads/search-users - Price: 0.6 credits ($0.003) per result
- Launched: 2026-11-17
- Example body:
payloads/search-users.json
Find Threads accounts by name or username. Each match returns the username, display name, profile URL, avatar and verification status, so you can confirm the right handle before pulling posts or replies, or turn a list of names into Threads profiles for influencer research.
Provide a name or username in query. Each search returns the accounts Threads suggests for it, usually up to 10. Each account costs 0.6 credits.
| Field | Type | Required | Description |
|---|---|---|---|
callback_url |
string (uri) | No | - |
query |
string | Yes | Search query. |
curl -X POST "https://api.socq.ai/v1/threads/search-users" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "shams"
}'Full docs: https://docs.socq.ai/api-manual/threads/search-users · Landing page: socq.ai/apis/threads/search-users
Collect the latest public replies a Threads account has posted, with engagement and media.
- Request:
POST https://api.socq.ai/v1/threads/user-replies - publicId:
threads/user-replies - Price: 0.5 credits ($0.0025) per result
- Launched: 2026-11-17
- Example body:
payloads/user-replies.json
See how an account behaves in other people's threads. You get its latest public replies with text, likes, replies, media, time and a link to each reply. Replies show tone and expertise more directly than polished posts, which makes them useful for vetting creators, monitoring a spokesperson, or studying how a brand handles customer conversations.
Provide Threads profile URLs in urls, such as https://www.threads.com/@username. Each profile returns its latest public replies, up to about 25. Each reply returned costs 0.5 credits.
| Field | Type | Required | Description |
|---|---|---|---|
callback_url |
string (uri) | No | - |
urls |
array of string | Yes | Public profile or content URLs. (items at least 1) |
curl -X POST "https://api.socq.ai/v1/threads/user-replies" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"urls": [
"https://www.threads.com/@reuters"
]
}'Full docs: https://docs.socq.ai/api-manual/threads/user-replies · Landing page: socq.ai/apis/threads/user-replies
Collect the posts a Threads account has reposted, each shown with its original author.
- Request:
POST https://api.socq.ai/v1/threads/user-reposts - publicId:
threads/user-reposts - Price: 0.5 credits ($0.0025) per result
- Launched: 2026-11-17
- Example body:
payloads/user-reposts.json
Get the posts an account chose to repost on Threads. Each row is the original post with its author, text, engagement and media, so you can see whose content an account amplifies. Repost history is a direct signal of affinity: it maps the voices a creator trusts, the partners a brand promotes, and the content that spreads through a community.
Provide Threads profile URLs in urls, such as https://www.threads.com/@username. Each profile returns the posts it has recently reposted, up to about 25, each shown with its original author. Each post returned costs 0.5 credits.
| Field | Type | Required | Description |
|---|---|---|---|
callback_url |
string (uri) | No | - |
urls |
array of string | Yes | Public profile or content URLs. (items at least 1) |
curl -X POST "https://api.socq.ai/v1/threads/user-reposts" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"urls": [
"https://www.threads.com/@shams"
]
}'Full docs: https://docs.socq.ai/api-manual/threads/user-reposts · Landing page: socq.ai/apis/threads/user-reposts
| Path | Purpose |
|---|---|
examples/curl/socq.sh |
Submit, poll and paginate with cURL and jq |
examples/node/socq.mjs |
Same workflow in Node.js 20+ (no dependencies) |
examples/python/socq.py |
Same workflow in Python 3.8+ (standard library) |
payloads/ |
One documented request body per endpoint |
endpoints.json |
Endpoint list, prices and request schemas used by the scripts and checks |
fixtures/ |
Synthetic submit and task response shapes |
docs/production-notes.md |
Retries, timeouts, pagination and data handling |
scripts/check.mjs |
Offline check: payloads, syntax and secrets |
- Use only publicly accessible Threads data and the fields supported by each endpoint.
- Do not use the examples to access restricted content, login-only surfaces, authentication controls or non-public personal information.
- SocQ is not an official API of the represented platform and is not affiliated with or endorsed by it. Platform names and trademarks belong to their respective owners.
- Before production use, assess the laws, platform terms, privacy obligations and retention requirements that apply to your organization and use case.
- Collect only the fields needed for a defined purpose, restrict access, set retention periods, and support correction or deletion workflows where required.
This section describes the public-data boundary; it is not legal advice.