search

Search for content in accounts, statuses and hashtags.

Search results

GET https://mastodon.example/api/v2/search

Returns: Results OAuth: User token + read:search Version history: 2.4.1 - added, limit hardcoded to 5 2.8.0 - add type, limit, offset, min_id, max_id, account_id 3.0.0 - add exclude_unreviewed param

Query Parameters

Name	Type	Description
account_id	string	If provided, statuses returned will be authored only by this account
max_id	string	Return results older than this id
min_id	string	Return results immediately newer than this id
type	string	Enum(accounts, hashtags, statuses)
exclude_unreviewed	boolean	Filter out unreviewed tags? Defaults to false. Use true when trying to find trending tags.
q	string	The search query
resolve	boolean	Attempt WebFinger lookup. Defaults to false.
limit	integer	Maximum number of results to load, per type. Defaults to 20. Max 40.
offset	integer	Offset in search results. Used for pagination. Defaults to 0.
following	boolean	Only include accounts that the user is following. Defaults to false.

Headers

Name	Type	Description
Authorization	string	Bearer <user token>

200 Truncated results of a sample search for "cats" with limit=2.

{
  "accounts": [
    {
      "id": "180744",
      "username": "catstar",
      "acct": "[e-mail]",
      "display_name": "catstar",
      ...
    },
    {
      "id": "214293",
      "username": "catsareweird",
      "acct": "catsareweird",
      "display_name": "Cats Are Weird",
      ...
    }
  ],
  "statuses": [
    {
      "id": "103085519055545958",
      "created_at": "2019-11-05T13:23:09.000Z",
      ...
      "content": "<p>cats<br>cats never change</p>",
      ...
    },
    {
      "id": "101068121469614510",
      "created_at": "2018-11-14T06:31:48.000Z",
      ...
      "spoiler_text": "Cats",
      ...
      "content": "<p>Cats are inherently good at self-care. </p><p><a href=\"https://mspsocial.net/tags/cats\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>cats</span></a></p>",
      ...
  ],
  "hashtags": [
    {
      "name": "cats",
      "url": "https://mastodon.social/tags/cats",
      "history": [
        {
          "day": "1574553600",
          "uses": "10",
          "accounts": "9"
        },
        ...
      ]
    },
    {
      "name": "catsofmastodon",
      "url": "https://mastodon.social/tags/catsofmastodon",
      "history": [
        {
          "day": "1574553600",
          "uses": "6",
          "accounts": "5"
        },
        ...
      ]
    }
  ]
}

401 Invalid or missing Authorization header

{
  "error": "The access token is invalid"
}

(DEPRECATED) Search results

GET https://mastodon.example/api/v1/search

Returns: Results, but hashtags is an array of strings instead of an array of Tag. OAuth: User token + read:search Version history: 1.1 - added, limit hardcoded to 5 1.5.0 - now requires authentication 2.8.0 - added limit, pagination, and account options 3.0.0 - removed; use v2 instead

Query Parameters

Name	Type	Description
q	string	The search query
resolve	string	Attempt Webfinger lookup. Defaults to false.
limit	string	Max number of results to load per type. Defaults to 20
type	string	Enum(accounts,hashtags,statuses)
offset	string	Offset in search results.
min_id	string	Return results immediately newer than this id
max_id	string	Return results older than this id
account_id	string	Return statuses only from this account

200 v1 search was deprecated because hashtags were returned as strings instead of as Tag entities.

{
  "accounts": [...],
  "statuses": [...],
  "hashtags": ["cats","catsofmastodon"]
}

401 Invalid or missing Authorization header

{
  "error": "The access token is invalid"
}