AsyncMentionClient - Mention Python Client

Overview

The AsyncMentionClient class provides a typed, asynchronous interface for interacting with all Mention API endpoints. It mirrors the functionality of MentionClient but uses async/await syntax for non-blocking I/O operations.

Constructor

AsyncMentionClient(
    access_token: str,
    *,
    base_url: str = "https://api.mention.net/api",
    timeout: float = 30.0,
    max_retries: int = 3,
    retry_delay: float = 1.0,
) -> None

Parameters

access_token

str

required

OAuth2 access token for authentication

base_url

str

default:"https://api.mention.net/api"

Base URL for the Mention API

timeout

float

default:"30.0"

Request timeout in seconds

max_retries

int

default:"3"

Maximum number of retry attempts for failed requests

retry_delay

float

default:"1.0"

Base delay between retries in seconds (uses exponential backoff)

Class Methods

from_config

@classmethod
def from_config(cls, config: MentionConfig) -> AsyncMentionClient

Create an async client from a MentionConfig instance. Parameters:

config (MentionConfig): Configuration object

Returns: Configured AsyncMentionClient instance

Public Methods

All methods are asynchronous and must be awaited. The API mirrors the synchronous MentionClient.

App Data

get_app_data

async def get_app_data(self) -> AppData

Retrieve application data. Returns: AppData object with application configuration

Account Methods

create_account

async def create_account(
    self,
    name: str,
    email: str,
    password: str,
    company: str | None = None,
    language: str = "en",
    timezone: str = "UTC",
) -> Account

Create a new account. Returns: Created Account object

get_account

async def get_account(self, account_id: str) -> Account

Fetch a single account by ID. Returns: Account object

get_account_me

async def get_account_me(self) -> Account

Fetch the current user’s account. Returns: Account object for the authenticated user

update_account

async def update_account(
    self,
    account_id: str,
    name: str | None = None,
    email: str | None = None,
    company: str | None = None,
    language: str | None = None,
    timezone: str | None = None,
) -> Account

Update an existing account. Returns: Updated Account object

delete_account

async def delete_account(self, account_id: str) -> bool

Delete an account. Returns: True if deletion was successful

Alert Methods

get_alerts

async def get_alerts(self, account_id: str) -> AlertsResponse

Fetch all alerts for an account. Returns: AlertsResponse containing list of alerts

get_alert

async def get_alert(self, account_id: str, alert_id: str) -> Alert

Fetch a single alert by ID. Returns: Alert object

create_alert

async def create_alert(self, account_id: str, request: CreateAlertRequest) -> Alert

Create a new alert. Returns: Created Alert object

update_alert

async def update_alert(
    self,
    account_id: str,
    alert_id: str,
    request: UpdateAlertRequest,
) -> Alert

Update an existing alert. Returns: Updated Alert object

delete_alert

async def delete_alert(self, account_id: str, alert_id: str) -> bool

Delete an alert. Returns: True if deletion was successful

pause_alert

async def pause_alert(self, account_id: str, alert_id: str) -> bool

Pause an alert (stop monitoring). Returns: True if pause was successful

unpause_alert

async def unpause_alert(self, account_id: str, alert_id: str) -> bool

Unpause an alert (resume monitoring). Returns: True if unpause was successful

Mention Methods

get_mentions

async def get_mentions(
    self,
    account_id: str,
    alert_id: str,
    *,
    limit: int = 100,
    before_date: datetime | str | None = None,
    not_before_date: datetime | str | None = None,
    since_id: str | None = None,
    source: str | None = None,
    read: bool | None = None,
    favorite: bool | None = None,
    tone: str | None = None,
    cursor: str | None = None,
) -> MentionsResponse

Fetch mentions for an alert. Returns: MentionsResponse containing list of mentions

get_mention

async def get_mention(
    self,
    account_id: str,
    alert_id: str,
    mention_id: str,
) -> Mention

Fetch a single mention by ID. Returns: Mention object

curate_mention

async def curate_mention(
    self,
    account_id: str,
    alert_id: str,
    mention_id: str,
    request: CurateMentionRequest,
) -> Mention

Update/curate a mention. Returns: Updated Mention object

mark_all_mentions_read

async def mark_all_mentions_read(self, account_id: str, alert_id: str) -> bool

Mark all mentions for an alert as read. Returns: True if successful

get_mention_children

async def get_mention_children(
    self,
    account_id: str,
    alert_id: str,
    mention_id: str,
) -> MentionsResponse

Fetch child mentions (replies, comments) of a mention. Returns: MentionsResponse containing child mentions

stream_mentions

async def stream_mentions(
    self,
    account_id: str,
    alert_id: str,
    *,
    since: datetime | str | None = None,
) -> AsyncIterator[Mention]

Stream mentions in real-time using long-polling. Yields: Mention objects as they arrive

Task Methods

get_tasks

async def get_tasks(self, account_id: str, alert_id: str) -> TasksResponse

Fetch all tasks for an alert. Returns: TasksResponse containing list of tasks

get_mention_tasks

async def get_mention_tasks(
    self,
    account_id: str,
    alert_id: str,
    mention_id: str,
) -> TasksResponse

Fetch all tasks for a specific mention. Returns: TasksResponse containing list of tasks

get_task

async def get_task(
    self,
    account_id: str,
    alert_id: str,
    mention_id: str,
    task_id: str,
) -> Task

Fetch a single task by ID. Returns: Task object

create_task

async def create_task(
    self,
    account_id: str,
    alert_id: str,
    mention_id: str,
    request: CreateTaskRequest,
) -> Task

Create a new task for a mention. Returns: Created Task object

update_task

async def update_task(
    self,
    account_id: str,
    alert_id: str,
    mention_id: str,
    task_id: str,
    request: UpdateTaskRequest,
) -> Task

Update an existing task. Returns: Updated Task object

delete_task

async def delete_task(
    self,
    account_id: str,
    alert_id: str,
    mention_id: str,
    task_id: str,
) -> bool

Delete a task. Returns: True if deletion was successful

Tag Methods

get_tags

async def get_tags(self, account_id: str, alert_id: str) -> TagsResponse

Fetch all tags for an alert. Returns: TagsResponse containing list of tags

create_tag

async def create_tag(
    self,
    account_id: str,
    alert_id: str,
    request: CreateTagRequest,
) -> Tag

Create a new tag for an alert. Returns: Created Tag object

update_tag

async def update_tag(
    self,
    account_id: str,
    alert_id: str,
    tag_id: str,
    request: UpdateTagRequest,
) -> Tag

Update an existing tag. Returns: Updated Tag object

delete_tag

async def delete_tag(self, account_id: str, alert_id: str, tag_id: str) -> bool

Delete a tag. Returns: True if deletion was successful

get_shares

async def get_shares(self, account_id: str, alert_id: str) -> SharesResponse

Fetch all shares for an alert. Returns: SharesResponse containing list of shares

get_share

async def get_share(self, account_id: str, alert_id: str, share_id: str) -> Share

Fetch a single share by ID. Returns: Share object

create_share

async def create_share(
    self,
    account_id: str,
    alert_id: str,
    request: CreateShareRequest,
) -> Share

Create a new share for an alert. Returns: Created Share object

update_share

async def update_share(
    self,
    account_id: str,
    alert_id: str,
    share_id: str,
    request: UpdateShareRequest,
) -> Share

Update an existing share. Returns: Updated Share object

delete_share

async def delete_share(self, account_id: str, alert_id: str, share_id: str) -> bool

Delete a share. Returns: True if deletion was successful

Preferences Methods

get_preferences

async def get_preferences(self, account_id: str, alert_id: str) -> AlertPreferences

Fetch preferences for an alert. Returns: AlertPreferences object

update_preferences

async def update_preferences(
    self,
    account_id: str,
    alert_id: str,
    request: UpdatePreferencesRequest,
) -> AlertPreferences

Update preferences for an alert. Returns: Updated AlertPreferences object

Authors Methods

get_authors

async def get_authors(
    self,
    account_id: str,
    alert_id: str,
    *,
    limit: int = 100,
    sort_by: str | None = None,
) -> AuthorsResponse

Fetch authors/influencers for an alert. Returns: AuthorsResponse containing list of authors

Statistics Methods

get_stats

async def get_stats(
    self,
    account_id: str,
    alert_id: str | None = None,
    *,
    from_date: datetime | str | None = None,
    to_date: datetime | str | None = None,
    period: StatsPeriod = StatsPeriod.DAY,
) -> StatsResponse

Fetch statistics for an account or alert. Returns: StatsResponse containing statistics data

Context Manager

close

async def close(self) -> None

Close the underlying HTTP client.

Async Context Manager Support

The AsyncMentionClient supports the async context manager protocol for automatic resource cleanup:

async with AsyncMentionClient(access_token="token") as client:
    data = await client.get_app_data()
    # Client is automatically closed when exiting the context

Usage Examples

Basic Usage

import asyncio
from mention import AsyncMentionClient

async def main():
    async with AsyncMentionClient(access_token="token") as client:
        alerts = await client.get_alerts("account-id")
        print(alerts)

asyncio.run(main())

Using Configuration

import asyncio
from mention import AsyncMentionClient, MentionConfig

async def main():
    config = MentionConfig.from_env()
    async with AsyncMentionClient.from_config(config) as client:
        data = await client.get_app_data()
        print(data)

asyncio.run(main())

Streaming Mentions

import asyncio
from mention import AsyncMentionClient

async def main():
    async with AsyncMentionClient(access_token="token") as client:
        async for mention in client.stream_mentions("account-id", "alert-id"):
            print(f"New mention: {mention.title}")

asyncio.run(main())

Core

Resources

Models

Exceptions

​Overview

​Constructor

​Parameters

​Class Methods

​from_config

​Public Methods

​App Data

​get_app_data

​Account Methods

​create_account

​get_account

​get_account_me

​update_account

​delete_account

​Alert Methods

​get_alerts

​get_alert

​create_alert

​update_alert

​delete_alert

​pause_alert

​unpause_alert

​Mention Methods

​get_mentions

​get_mention

​curate_mention

​mark_all_mentions_read

​get_mention_children

​stream_mentions

​Task Methods

​get_tasks

​get_mention_tasks

​get_task

​create_task

​update_task

​delete_task

​Tag Methods

​get_tags

​create_tag

​update_tag

​delete_tag

​Share Methods

​get_shares

​get_share

​create_share

​update_share

​delete_share

​Preferences Methods

​get_preferences

​update_preferences

​Authors Methods

​get_authors

​Statistics Methods

​get_stats

​Context Manager

​close

​Async Context Manager Support

​Usage Examples

​Basic Usage

​Using Configuration

​Streaming Mentions

Build docs developers (and LLMs) love