0
# Search & Discovery
1

2
Comprehensive search functionality across accounts, statuses, and hashtags with support for both v1 and v2 search APIs. Enables applications to find and discover content across the Mastodon network.
3

4
## Capabilities
5

6
### General Search
7

8
Search across multiple content types with intelligent routing between API versions based on instance capabilities.
9

10
```python { .api }
11
def search(
12
    self,
13
    q: str,
14
    resolve: bool = True,
15
    result_type: str = None,
16
    account_id: Union[Account, int] = None,
17
    offset: int = None,
18
    min_id: int = None,
19
    max_id: int = None,
20
    exclude_unreviewed: bool = True
21
) -> Union[Search, SearchV2]:
22
    """
23
    Search for hashtags, accounts, and statuses across the network.
24
    
25
    Args:
26
        q: Search query string
27
        resolve: Perform webfinger lookups for remote accounts/statuses
28
        result_type: Limit results to specific type ("accounts", "hashtags", "statuses")
29
        account_id: Only return results from this specific account
30
        offset: Pagination offset for results
31
        min_id: Return results newer than this ID
32
        max_id: Return results older than this ID
33
        exclude_unreviewed: Exclude unreviewed hashtags from results (Mastodon 3.0.0+)
34
    
35
    Returns:
36
        Dictionary containing search results with "accounts", "statuses", and "hashtags" keys
37
    """
38
```
39

40
### Advanced Search (v2)
41

42
More sophisticated search with enhanced filtering and pagination options.
43

44
```python { .api }
45
def search_v2(
46
    self,
47
    q: str,
48
    resolve: bool = True,
49
    result_type: str = None,
50
    account_id: Union[Account, int] = None,
51
    offset: int = None,
52
    min_id: int = None,
53
    max_id: int = None,
54
    exclude_unreviewed: bool = True
55
) -> SearchV2:
56
    """
57
    Advanced search API with enhanced features and object-based hashtag results.
58
    
59
    Args:
60
        q: Search query string
61
        resolve: Perform webfinger lookups (default: True for v2)
62
        result_type: Filter by content type ("accounts", "hashtags", "statuses") 
63
        account_id: Restrict search to specific account's content
64
        offset: Pagination offset (Mastodon 2.8.0+)
65
        min_id: Pagination - results newer than this ID (Mastodon 2.8.0+)
66
        max_id: Pagination - results older than this ID (Mastodon 2.8.0+)
67
        exclude_unreviewed: Exclude unreviewed hashtags (Mastodon 3.0.0+)
68
    
69
    Returns:
70
        Search results with hashtags as full objects (including usage stats)
71
    """
72
```
73

74
### Legacy Search (v1)
75

76
Basic search functionality for older Mastodon instances.
77

78
```python { .api }
79
def search_v1(self, q: str, resolve: bool = False) -> Search:
80
    """
81
    Legacy search API for Mastodon instances before 2.4.1.
82
    
83
    Args:
84
        q: Search query string
85
        resolve: Perform webfinger lookups (default: False for v1)
86
    
87
    Returns:
88
        Basic search results with hashtags as strings rather than objects
89
        
90
    Note:
91
        This method should not be used directly - use search() instead
92
        which automatically selects the appropriate API version.
93
    """
94
```
95

96
## Usage Examples
97

98
### Basic Search
99

100
```python
101
from mastodon import Mastodon
102

103
mastodon = Mastodon(access_token='your_token.secret')
104

105
# Search for everything related to "python"
106
results = mastodon.search("python")
107
print(f"Found {len(results['accounts'])} accounts")
108
print(f"Found {len(results['statuses'])} statuses") 
109
print(f"Found {len(results['hashtags'])} hashtags")
110

111
# Search only for accounts
112
accounts = mastodon.search("python", result_type="accounts")
113
for account in accounts['accounts']:
114
    print(f"@{account['acct']}: {account['display_name']}")
115
```
116

117
### Advanced Search with Pagination
118

119
```python
120
# Search for recent posts about Python with pagination
121
results = mastodon.search(
122
    "python programming", 
123
    result_type="statuses",
124
    limit=20,
125
    resolve=True
126
)
127

128
# Get older results using max_id
129
if results['statuses']:
130
    older_results = mastodon.search(
131
        "python programming",
132
        result_type="statuses", 
133
        max_id=results['statuses'][-1]['id']
134
    )
135
```
136

137
### Search Specific Account
138

139
```python
140
# Find posts from a specific account
141
account = mastodon.account_lookup("gargron@mastodon.social")
142
results = mastodon.search(
143
    "federation",
144
    account_id=account['id'],
145
    result_type="statuses"
146
)
147
```
148

149
## Return Types
150

151
Search results are returned as dictionaries with the following structure:
152

153
```python
154
{
155
    "accounts": [
156
        {
157
            "id": "123",
158
            "username": "user",
159
            "acct": "user@example.com", 
160
            "display_name": "User Name",
161
            # ... other account fields
162
        }
163
    ],
164
    "statuses": [
165
        {
166
            "id": "456", 
167
            "content": "<p>Status content</p>",
168
            "account": { /* account object */ },
169
            # ... other status fields
170
        }
171
    ],
172
    "hashtags": [
173
        # v1: ["hashtag1", "hashtag2"]
174
        # v2: [{"name": "hashtag1", "history": [...], ...}]
175
    ]
176
}
177
```
178

179
## Version Compatibility
180

181
The search API automatically adapts to your Mastodon instance version:
182

183
- **Mastodon < 2.4.1**: Uses `search_v1()` with basic functionality
184
- **Mastodon 2.4.1+**: Uses `search_v2()` with object-based hashtags  
185
- **Mastodon 2.8.0+**: Advanced parameters (account_id, offset, pagination) available
186
- **Mastodon 3.0.0+**: `exclude_unreviewed` parameter for hashtag filtering
187

188
Parameters not supported by your instance version will raise a `MastodonVersionError`.