2020-01-01 22:37:59 +01:00
---
title: search
description: 'Search for content in accounts, statuses and hashtags.'
menu:
docs:
weight: 60
parent: methods
---
{{< api-method method = "get" host = "https://mastodon.example" path = "/api/v2/search" title = "Search results" > }}
{{< api-method-description > }}
**Returns:** Results\
**OAuth:** User token + `read:search` \
2020-12-27 07:03:55 +01:00
**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
2020-01-01 22:37:59 +01:00
{{< endapi-method-description > }}
{{< api-method-spec > }}
{{< api-method-request > }}
{{< api-method-headers > }}
{{< api-method-parameter name = "Authorization" type = "string" required = true > }}
Bearer < user token>
{{< endapi-method-parameter > }}
{{< endapi-method-headers > }}
{{< api-method-query-parameters > }}
{{< api-method-parameter name = "account_id" type = "string" required = false > }}
If provided, statuses returned will be authored only by this account
{{< endapi-method-parameter > }}
{{< api-method-parameter name = "max_id" type = "string" required = false > }}
Return results older than this id
{{< endapi-method-parameter > }}
{{< api-method-parameter name = "min_id" type = "string" required = false > }}
Return results immediately newer than this id
{{< endapi-method-parameter > }}
{{< api-method-parameter name = "type" type = "string" required = false > }}
Enum\(accounts, hashtags, statuses\)
{{< endapi-method-parameter > }}
{{< api-method-parameter name = "exclude_unreviewed" type = "boolean" required = false > }}
Filter out unreviewed tags? Defaults to false. Use true when trying to find trending tags.
{{< endapi-method-parameter > }}
{{< api-method-parameter name = "q" type = "string" required = true > }}
The search query
{{< endapi-method-parameter > }}
{{< api-method-parameter name = "resolve" type = "boolean" required = false > }}
Attempt WebFinger lookup. Defaults to false.
{{< endapi-method-parameter > }}
{{< api-method-parameter name = "limit" type = "integer" required = false > }}
Maximum number of results to load, per type. Defaults to 20. Max 40.
{{< endapi-method-parameter > }}
{{< api-method-parameter name = "offset" type = "integer" required = false > }}
Offset in search results. Used for pagination. Defaults to 0.
{{< endapi-method-parameter > }}
{{< api-method-parameter name = "following" type = "boolean" required = false > }}
Only include accounts that the user is following. Defaults to false.
{{< endapi-method-parameter > }}
{{< endapi-method-query-parameters > }}
{{< endapi-method-request > }}
{{< api-method-response > }}
{{< api-method-response-example httpCode = 200 > }}
{{< api-method-response-example-description > }}
Truncated results of a sample search for "cats" with limit=2.
{{< endapi-method-response-example-description > }}
```javascript
{
"accounts": [
{
"id": "180744",
"username": "catstar",
"acct": "catstar@catgram.jp",
"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"
},
...
]
}
]
}
```
{{< endapi-method-response-example > }}
{{< api-method-response-example httpCode = 401 > }}
{{< api-method-response-example-description > }}
Invalid or missing Authorization header
{{< endapi-method-response-example-description > }}
```javascript
{
"error": "The access token is invalid"
}
```
{{< endapi-method-response-example > }}
{{< endapi-method-response > }}
{{< endapi-method-spec > }}
{{< endapi-method > }}
{{< api-method method = "get" host = "https://mastodon.example" path = "/api/v1/search" title = " \(DEPRECATED \) Search results" > }}
{{< api-method-description > }}
**Returns:** Results, but hashtags is an array of strings instead of an array of Tag.\
**OAuth:** User token + `read:search` \
**Version history:**\
2020-12-27 07:03:55 +01:00
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
2020-01-01 22:37:59 +01:00
{{< endapi-method-description > }}
{{< api-method-spec > }}
{{< api-method-request > }}
{{< api-method-query-parameters > }}
{{< api-method-parameter name = "q" type = "string" required = true > }}
The search query
{{< endapi-method-parameter > }}
{{< api-method-parameter name = "resolve" type = "string" required = false > }}
Attempt Webfinger lookup. Defaults to false.
{{< endapi-method-parameter > }}
{{< api-method-parameter name = "limit" type = "string" required = false > }}
Max number of results to load per type. Defaults to 20
{{< endapi-method-parameter > }}
{{< api-method-parameter name = "type" type = "string" required = false > }}
Enum\(accounts,hashtags,statuses\)
{{< endapi-method-parameter > }}
{{< api-method-parameter name = "offset" type = "string" required = false > }}
Offset in search results.
{{< endapi-method-parameter > }}
{{< api-method-parameter name = "min_id" type = "string" required = false > }}
Return results immediately newer than this id
{{< endapi-method-parameter > }}
{{< api-method-parameter name = "max_id" type = "string" required = false > }}
Return results older than this id
{{< endapi-method-parameter > }}
{{< api-method-parameter name = "account_id" type = "string" required = false > }}
Return statuses only from this account
{{< endapi-method-parameter > }}
{{< endapi-method-query-parameters > }}
{{< endapi-method-request > }}
{{< api-method-response > }}
{{< api-method-response-example httpCode = 200 > }}
{{< api-method-response-example-description > }}
v1 search was deprecated because hashtags were returned as strings instead of as Tag entities.
{{< endapi-method-response-example-description > }}
```javascript
{
"accounts": [...],
"statuses": [...],
"hashtags": ["cats","catsofmastodon"]
}
```
{{< endapi-method-response-example > }}
{{< api-method-response-example httpCode = 401 > }}
{{< api-method-response-example-description > }}
Invalid or missing Authorization header
{{< endapi-method-response-example-description > }}
```javascript
{
"error": "The access token is invalid"
}
```
{{< endapi-method-response-example > }}
{{< endapi-method-response > }}
{{< endapi-method-spec > }}
{{< endapi-method > }}