Skip to content

About

SocQ Threads API examples in cURL, Node.js and Python: 8 endpoints for posts, profiles, user posts, post replies, search, user search, user replies and user reposts. Pay per call or per result.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Threads API

SocQ Threads API API documentation License: MIT Check examples

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

Endpoints

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

Quick start

  1. Create an API key at socq.ai/dashboard/api-key.
  2. 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"
  1. 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.

How the API works

Base URL https://api.socq.ai. Every request sends the API key as a bearer token:

Authorization: Bearer <SOCQ_API_KEY>
Content-Type: application/json

All endpoints are asynchronous:

POST /v1/<publicId>  ->  data.task_id  ->  GET /v1/tasks/{task_id}  ->  queued | running | succeeded | failed
  1. Submit the JSON body to POST https://api.socq.ai/v1/<publicId>. The response returns data.task_id immediately; it means the task was created, not that data is ready.
  2. Poll GET https://api.socq.ai/v1/tasks/{task_id} until data.status is succeeded or failed (a failed task carries data.error_message).
  3. Read results. A succeeded task returns normalized records in data.results.items. Use limit (default 50, max 500) and pass data.results.next_cursor as cursor while data.results.has_more is true. fields selects up to 50 comma-separated fields or dot paths.
  4. Raw files (optional). GET https://api.socq.ai/v1/tasks/{task_id}/files lists 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

Endpoint reference

Threads Posts API

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

Threads Profiles API

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

Threads User Posts API

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

Threads Post Replies API

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

Threads Search API

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

Threads User Search API

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

Threads User Replies API

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

Threads User Reposts API

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

Repository contents

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

Responsible use and platform scope

  • 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.

License

MIT

About

SocQ Threads API examples in cURL, Node.js and Python: 8 endpoints for posts, profiles, user posts, post replies, search, user search, user replies and user reposts. Pay per call or per result.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages