search

Search for content in accounts, statuses and hashtags.

get
Search results

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

Request

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

Response

200: Success

Truncated results of a sample search for “cats” with limit=2.

{
  "accounts": [
    {
      "id": "180744",
      "username": "catstar",
      "acct": "[email protected]",
      "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: Unauthorized

Invalid or missing Authorization header

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

get
\(DEPRECATED\) Search results

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

Request

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

Response

200: Success

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

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

401: Unauthorized

Invalid or missing Authorization header

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

Last updated December 27, 2020 · Improve this page