Twitter Search API

Twitter Search

Features

• Discovery from one expressionSubmit a non-empty keyword or search expression and turn its matching public X posts into structured records.
• Ordering for two research modesUse latest to follow recent matches or top to review prominent matches, with latest selected by default.
• A practical search-result capRequest 20 to 2,000 results in increments of 20 to set the maximum depth of the search collection.
• Matches that retain their queryCombine text, author, engagement, media, entities, timestamps, and relationship fields with extra.search_query and collected_at.

Parameters

How to Use

Frame a precise research question as a search expression, select the ordering that fits it, and preserve the query with the resulting posts.

1. Write one focused, non-empty expression for the X posts you want to find.
2. Select latest or top and choose a results_limit from 20 to 2,000 in increments of 20.
3. POST the request to /v1/x/search, then poll /v1/tasks/{task_id} until completion.
4. Store data.results.items, then follow next_cursor until has_more becomes false.

curl -X POST "https://api.socq.ai/v1/x/search" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"artificial intelligence","results_limit":40,"sort_by":"latest"}'

# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is true

Best Use Cases

• Listen around a named launch: Search a product, release, conference, or campaign phrase and organize matching posts by publication and collection time.
• Track brand and product mentions: Bring authors, text, visible engagement, hashtags, mentions, and media together for a focused name or phrase.
• Map a developing topic: Use latest results to follow new posts and top results to inspect prominent content within the same research expression.
• Maintain a recurring query dataset: Store extra.search_query with every match, rerun a versioned expression, and append only previously unseen post IDs.

Pro Tips

• Begin with a focused expression, inspect the matches, and broaden the wording only when coverage is too narrow.
• Choose latest for time-sensitive listening and top when prominent matches matter more than chronology.
• Set results_limit as a multiple of 20 and interpret it as a cap, not a guaranteed result count.
• Version the query whenever its terms change so recurring result sets remain comparable.
• Deduplicate by post id while retaining extra.search_query and collected_at for discovery context.

Related APIs