Mentions

Overview

The Mentions API provides comprehensive methods for retrieving, filtering, and curating mentions. It supports pagination, real-time streaming, filtering by multiple criteria, and bulk operations.

Methods

Get Mentions

Fetch mentions for an alert with advanced filtering options.

client.get_mentions(
    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

account_id

string

required

The account ID

alert_id

string

required

The alert ID

limit

integer

default:"100"

Maximum number of mentions to return (max 1000)

before_date

datetime | string

Return mentions before this date (ISO 8601 format)

not_before_date

datetime | string

Return mentions on or after this date (ISO 8601 format)

since_id

string

Return mentions since this mention ID

source

string

Filter by source type (twitter, facebook, news, etc.)

read

boolean

Filter by read status

favorite

boolean

Filter by favorite status

tone

string

Filter by tone (positive, negative, neutral)

cursor

string

Pagination cursor for retrieving next page

Returns: MentionsResponse containing list of mentions and pagination info Example:

from mention import MentionClient
from datetime import datetime, timedelta

client = MentionClient(access_token="your-token")

# Get recent unread mentions
response = client.get_mentions(
    "acc_123456",
    "alert_123",
    limit=50,
    read=False,
    not_before_date=datetime.now() - timedelta(days=7)
)

for mention in response.mentions:
    print(f"{mention.title} - {mention.source_name}")
    print(f"Tone: {mention.tone}, Reach: {mention.reach}")

print(f"Total: {len(response.mentions)}")
print(f"Has more: {response.has_more}")

Response:

{
  "mentions": [
    {
      "id": "mention_789",
      "title": "Great product from Acme!",
      "description": "I've been using Acme's new service and it's amazing...",
      "description_short": "I've been using Acme's new service...",
      "original_url": "https://twitter.com/user/status/123",
      "source_name": "Twitter",
      "source_type": "twitter",
      "tone": "positive",
      "author": {
        "id": "author_456",
        "name": "John Doe",
        "username": "johndoe",
        "profile_url": "https://twitter.com/johndoe",
        "followers_count": 5000,
        "influence_score": 72.5
      },
      "tags": [
        {"id": "tag_1", "name": "Customer Feedback", "color": "#4CAF50"}
      ],
      "favorite": false,
      "read": false,
      "trashed": false,
      "published_at": "2024-01-20T14:30:00Z",
      "reach": 5000,
      "engagement": {
        "likes": 25,
        "shares": 5,
        "comments": 3
      },
      "language": "en",
      "country": "US",
      "created_at": "2024-01-20T14:35:00Z",
      "updated_at": "2024-01-20T14:35:00Z"
    }
  ],
  "has_more": true,
  "links": {
    "more": "cursor_xyz123"
  }
}

Iterate Mentions

Automatically paginate through all mentions.

client.iter_mentions(
    account_id: str,
    alert_id: str,
    *,
    limit: int = 100,
    **kwargs
) -> Iterator[Mention]

account_id

string

required

The account ID

alert_id

string

required

The alert ID

limit

integer

default:"100"

Number of mentions per page

**kwargs

any

Additional filters (same as get_mentions)

Yields: Mention objects Example:

Sync

# Iterate through all positive mentions
for mention in client.iter_mentions(
    "acc_123456",
    "alert_123",
    tone="positive",
    limit=100
):
    print(f"{mention.title} - {mention.reach}")
    
    # Process each mention
    if mention.reach > 10000:
        print(f"High reach mention: {mention.id}")

Get Mention

Fetch a single mention by ID.

client.get_mention(
    account_id: str,
    alert_id: str,
    mention_id: str
) -> Mention

account_id

string

required

The account ID

alert_id

string

required

The alert ID

mention_id

string

required

The mention ID

Returns: Mention object Example:

mention = client.get_mention(
    "acc_123456",
    "alert_123",
    "mention_789"
)

print(f"Title: {mention.title}")
print(f"Author: {mention.author.name}")
print(f"Sentiment: {mention.tone}")

Curate Mention

Update/curate a mention’s properties.

from mention import CurateMentionRequest

client.curate_mention(
    account_id: str,
    alert_id: str,
    mention_id: str,
    request: CurateMentionRequest
) -> Mention

account_id

string

required

The account ID

alert_id

string

required

The alert ID

mention_id

string

required

The mention ID

request

CurateMentionRequest

required

Curation request with updates (all fields optional)

Request Fields:

request.favorite

boolean

Mark as favorite

request.read

boolean

Mark as read/unread

request.trashed

boolean

Move to trash

request.tone

Tone

Override sentiment (positive, negative, neutral)

request.tags

list[string]

Tag IDs to apply

request.folder

string

Folder to move mention to

Returns: Updated Mention object Example:

from mention import CurateMentionRequest, Tone

request = CurateMentionRequest(
    favorite=True,
    read=True,
    tone=Tone.POSITIVE,
    tags=["tag_1", "tag_2"]
)

mention = client.curate_mention(
    "acc_123456",
    "alert_123",
    "mention_789",
    request
)

print(f"Updated: {mention.favorite}")

Mark All Mentions Read

Mark all mentions for an alert as read.

client.mark_all_mentions_read(
    account_id: str,
    alert_id: str
) -> bool

account_id

string

required

The account ID

alert_id

string

required

The alert ID

Returns: True if successful Example:

client.mark_all_mentions_read("acc_123456", "alert_123")
print("All mentions marked as read")

Get Mention Children

Fetch child mentions (replies, comments) of a mention.

client.get_mention_children(
    account_id: str,
    alert_id: str,
    mention_id: str
) -> MentionsResponse

account_id

string

required

The account ID

alert_id

string

required

The alert ID

mention_id

string

required

The parent mention ID

Returns: MentionsResponse containing child mentions Example:

children = client.get_mention_children(
    "acc_123456",
    "alert_123",
    "mention_789"
)

print(f"Found {len(children.mentions)} replies")
for child in children.mentions:
    print(f"Reply: {child.description_short}")

Stream Mentions

Stream mentions in real-time using long-polling.

client.stream_mentions(
    account_id: str,
    alert_id: str,
    *,
    since: datetime | str | None = None
) -> Iterator[Mention]

account_id

string

required

The account ID

alert_id

string

required

The alert ID

since

datetime | string

Start streaming from this timestamp

Yields: Mention objects as they arrive Example:

from datetime import datetime

# Stream mentions in real-time
for mention in client.stream_mentions(
    "acc_123456",
    "alert_123",
    since=datetime.now()
):
    print(f"New mention: {mention.title}")
    print(f"Source: {mention.source_name}")
    print(f"Sentiment: {mention.tone}")
    
    # Process new mention
    if mention.tone == "negative":
        print("ALERT: Negative mention detected!")

Models

Mention

Represents a single mention.

Field	Type	Description
`id`	`string`	Mention ID
`title`	`string`	Mention title
`description`	`string`	Full description/content
`description_short`	`string`	Shortened description
`original_url`	`string`	URL to original content
`source_name`	`string`	Source name (Twitter, Facebook, etc.)
`source_type`	`string`	Source type identifier
`tone`	`Tone`	Sentiment (positive, negative, neutral)
`author`	`Author`	Author information
`tags`	`list[Tag]`	Associated tags
`favorite`	`boolean`	Favorite status
`read`	`boolean`	Read status
`trashed`	`boolean`	Trash status
`published_at`	`datetime`	Publication timestamp
`reach`	`integer`	Estimated reach
`engagement`	`dict`	Engagement metrics (likes, shares, comments)
`language`	`string`	Language code
`country`	`string`	Country code
`image_url`	`string`	Associated image URL
`video_url`	`string`	Associated video URL
`created_at`	`datetime`	Creation timestamp
`updated_at`	`datetime`	Last update timestamp

Tone

Sentiment enumeration:

POSITIVE: Positive sentiment
NEGATIVE: Negative sentiment
NEUTRAL: Neutral sentiment

CurateMentionRequest

Request for updating mention properties.

Field	Type	Description
`favorite`	`boolean`	Favorite status
`read`	`boolean`	Read status
`trashed`	`boolean`	Trash status
`tone`	`Tone`	Override sentiment
`tags`	`list[string]`	Tag IDs
`folder`	`string`	Folder name

Core

Resources

Models

Exceptions

Overview

Methods

Get Mentions

Iterate Mentions

Get Mention

Curate Mention

Mark All Mentions Read

Get Mention Children

Stream Mentions

Models

Mention

Tone

CurateMentionRequest

Build docs developers (and LLMs) love

Core

Resources

Models

Exceptions

​Overview

​Methods

​Get Mentions

​Iterate Mentions

​Get Mention

​Curate Mention

​Mark All Mentions Read

​Get Mention Children

​Stream Mentions

​Models

​Mention

​Tone

​CurateMentionRequest

Build docs developers (and LLMs) love

Overview

Methods

Get Mentions

Iterate Mentions

Get Mention

Curate Mention

Mark All Mentions Read

Get Mention Children

Stream Mentions

Models

Mention

Tone

CurateMentionRequest