Keyword Search

Search for public Threads media with specific keywords.

Limitations

• You can send a maximum of 500 queries within a rolling 7 day period. Once a query is sent, it will count against this limit for 7 days. Subsequent queries against the same keyword within this timeframe will also count against your limit.
• Queries which return no results do not count against your limit. If no results are returned, consider refining or shortening your query.
• The API will return an empty array for any requests that include keywords that we have deemed sensitive or offensive.

Permissions

The Threads Keyword Search API requires an appropriate access token and permissions. While you are testing, you can easily generate tokens and grant your app permissions by using the Graph API Explorer.

• threads_basic — Required for making any calls to all Threads API endpoints.
• threads_keyword_search — Required for making GET calls to the keyword search endpoint.

If your app has not been approved for the threads_keyword_search permission, the search will be performed only on posts owned by the authenticated user. After approval, public posts will be searchable.

Keyword Search

To search for public Threads media by keyword, send a GET request to the /keyword_search endpoint with a keyword to be queried.

Parameters

See the Media documentation for a list of available fields. Note: The owner field is excluded and will not be returned.

Example Request

curl -s -X GET \
  -F "q=<KEYWORD>" \
  -F "search_type=TOP" \
  -F "fields=id,text,media_type,permalink,timestamp,username,has_replies,is_quote_post,is_reply" \
  -F "access_token=<THREADS_ACCESS_TOKEN>" \
"https://graph.threads.net/v1.0/keyword_search"

Example Response

{
  "data": [
    {
      "id": "1234567890",
      "text": "First Thread",
      "media_type": "TEXT",
      "permalink": "https://www.threads.net/@threadsapitestuser/post/abcdefg",
      "timestamp": "2023-10-17T05:42:03+0000",
      "username": "threadsapitestuser",
      "has_replies": false,
      "is_quote_post": false,
      "is_reply": false
    }
  ]
}

Interacting with Public Threads

You can interact with public Threads media that you have recently searched for. These actions include replying, quoting, and reposting.

Note: Additional permissions may be required as listed in those pages.

Recently Searched Keywords

You can retrieve a list of recently searched keywords for the currently authenticated user by sending a GET request to the /me endpoint and requesting the recently_searched_keywords field.

Example Request

curl -s -X GET \
  -F "fields=recently_searched_keywords" \
  -F "access_token=<THREADS_ACCESS_TOKEN>" \
"https://graph.threads.net/v1.0/me"

Example Response

{
  "id": "1234567890",
  "recently_searched_keywords": [
    {
      "query": "some keyword",
      "timestamp": 1735707600000,
    },
    {
      "query": "some other keyword",
      "timestamp": 1735707600000,
    }
  ]
}