Keyword and Topic Tag Search

Search for public Threads media with specific keywords or by topic tag.

Limitations

• A user can send a maximum of 2,200 queries within a rolling 24-hour period. Once a query is sent, it will count against this limit for 24 hours.
• This limit applies to a user across apps and is not differentiated for different apps. If multiple apps send requests for the same user, those queries will apply to the same limit for that user.
• Subsequent queries against the same keyword within this timeframe will also count against this limit.
• Queries which return no results do not count against this limit for the user. 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/@<USER>/post/abcdefg",
      "timestamp": "2023-10-17T05:42:03+0000",
      "username": "<USER>",
      "has_replies": false,
      "is_quote_post": false,
      "is_reply": false
    }
  ]
}

Topic Tag Search

To search for public Threads media by topic tag, send a GET request to the /keyword_search endpoint with a topic to be queried. To perform a topic tag search, you need to use the search_mode parameter and set the value to TAG.

Example Request

curl -s -X GET \
  -F "q=<TAG>" \
  -F "search_mode=TAG" \
  -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": "second thread",
      "media_type": "TEXT",
      "permalink": "https://www.threads.net/@<USER>/post/abcdefg",
      "timestamp": "2023-10-17T05:42:03+0000",
      "username": "<USER>",
      "has_replies": false,
      "is_quote_post": false,
      "is_reply": false
    }
  ]
}

Search by Media Type

To search for public Threads posts by media type, send a GET request to the /keyword_search endpoint with the media_type parameter. Searches can be done for text, image, and video media types. If the media_type parameter is not sent, all media types will be returned in the response.

Example Request

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

Example Response

{
  "data": [
    {
      "id": "1234567890",
      "text": "third thread",
      "media_type": "IMAGE",
      "permalink": "https://www.threads.net/@<USER>/post/abcdefg",
      "timestamp": "2023-10-17T05:42:03+0000",
      "username": "<USER>"
    }
  ]
}

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,
    }
  ]
}