Search & Discovery

def search(
    self,
    q: str,
    resolve: bool = True,
    result_type: str = None,
    account_id: Union[Account, int] = None,
    offset: int = None,
    min_id: int = None,
    max_id: int = None,
    exclude_unreviewed: bool = True
) -> Union[Search, SearchV2]:
    """
    Search for hashtags, accounts, and statuses across the network.
    
    Args:
        q: Search query string
        resolve: Perform webfinger lookups for remote accounts/statuses
        result_type: Limit results to specific type ("accounts", "hashtags", "statuses")
        account_id: Only return results from this specific account
        offset: Pagination offset for results
        min_id: Return results newer than this ID
        max_id: Return results older than this ID
        exclude_unreviewed: Exclude unreviewed hashtags from results (Mastodon 3.0.0+)
    
    Returns:
        Dictionary containing search results with "accounts", "statuses", and "hashtags" keys
    """

def search_v2(
    self,
    q: str,
    resolve: bool = True,
    result_type: str = None,
    account_id: Union[Account, int] = None,
    offset: int = None,
    min_id: int = None,
    max_id: int = None,
    exclude_unreviewed: bool = True
) -> SearchV2:
    """
    Advanced search API with enhanced features and object-based hashtag results.
    
    Args:
        q: Search query string
        resolve: Perform webfinger lookups (default: True for v2)
        result_type: Filter by content type ("accounts", "hashtags", "statuses") 
        account_id: Restrict search to specific account's content
        offset: Pagination offset (Mastodon 2.8.0+)
        min_id: Pagination - results newer than this ID (Mastodon 2.8.0+)
        max_id: Pagination - results older than this ID (Mastodon 2.8.0+)
        exclude_unreviewed: Exclude unreviewed hashtags (Mastodon 3.0.0+)
    
    Returns:
        Search results with hashtags as full objects (including usage stats)
    """

def search_v1(self, q: str, resolve: bool = False) -> Search:
    """
    Legacy search API for Mastodon instances before 2.4.1.
    
    Args:
        q: Search query string
        resolve: Perform webfinger lookups (default: False for v1)
    
    Returns:
        Basic search results with hashtags as strings rather than objects
        
    Note:
        This method should not be used directly - use search() instead
        which automatically selects the appropriate API version.
    """

from mastodon import Mastodon

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

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

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

# Search for recent posts about Python with pagination
results = mastodon.search(
    "python programming", 
    result_type="statuses",
    limit=20,
    resolve=True
)

# Get older results using max_id
if results['statuses']:
    older_results = mastodon.search(
        "python programming",
        result_type="statuses", 
        max_id=results['statuses'][-1]['id']
    )

# Find posts from a specific account
account = mastodon.account_lookup("gargron@mastodon.social")
results = mastodon.search(
    "federation",
    account_id=account['id'],
    result_type="statuses"
)

{
    "accounts": [
        {
            "id": "123",
            "username": "user",
            "acct": "user@example.com", 
            "display_name": "User Name",
            # ... other account fields
        }
    ],
    "statuses": [
        {
            "id": "456", 
            "content": "<p>Status content</p>",
            "account": { /* account object */ },
            # ... other status fields
        }
    ],
    "hashtags": [
        # v1: ["hashtag1", "hashtag2"]
        # v2: [{"name": "hashtag1", "history": [...], ...}]
    ]
}