Stream mention

GET /accounts/{account_id}/mentions?alerts[]={alert_id}

This method enables you to stream mentions for one or many alerts. It will open an http connection and keep it open, sending to your stream client any mention as soon as it is fetched for any of the selected alerts.

Only available through the https://stream.mention.net/api endpoint.

You can open one stream at the same time by {account_id}.

Parameters

  • account_id (string) - Id of the account

Page content

Minimal curl example

curl -ig 'https://stream.mention.net/api/accounts/{account_id}/mentions?alerts\[\]={alert_id}' \
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
    -H 'Accept-Version: 1.19'

Available properties

You can pass properties to this query via the querystring:

Properties _ Definition Example
alerts *required Array of alerts alerts[]=112233
since_id optional Map of last mention per alert since_id[112233]=42

Alerts

alerts

This require parameter is used to retrieve all mentions from specific alerts.

Since id

since_id

This parameter may be use to retrieve historical mentions per alert.

since_id is a multi-valued parameter with an alert id as key (in the example, 112233) and an mention id as value (in the example 42).

We send you a maximum of 1000 mentions per alert. When this limit is reached, we send you this message:

{"type":"warning","message":"Historical mentions capped to 1000."}

Request example

  • Querystring
alerts[]=112233&alerts[]=112234&since_id[112233]=42

Response example

{"type":"mark"}
{"type":"mention","mention": {...mention}}
{"type":"mention","mention": {...mention}}

Mark

We send this message as a keep-alive signal to prevent clients closing the stream connection each 30 seconds.

Mention

{
    "id": "527849933",
    "alert_id": 112233,
    "title": "NASA image shows 'starburst spider' pattern on Mars",
    "description": "USA TODAY NASA image shows 'starburst spider' pattern on Mars USA TODAY NASA's Mars Reconnaissance Orbiter captured a stunning image of a \"starburst\" pattern on Mars ' surface. The \u201cstarbursts\u201d can be seen each spring when Mars ' seasonal cap of carbon \u2026",
    "original_url": "http:\/\/www.usatoday.com\/story\/tech\/nation-now\/2016\/01\/14\/nasa-image-shows-starburst-spider-pattern-mars\/78781074\/",
    "clickable_url": "https:\/\/web.mention.com\/api\/url?token=eyJ0eXAiOiJKV1QiLChbGciOiJIUzI1NiJ9.eyJ1cmwiOJodHRwOlwvXC93d3cudXNhdG9kYkuY29tXC9zdG9eVwvdGVjaFwvbmF0a9uLW5vd1wvMjAxNlwvMDFcLzE0XC9uYXNLWltYWdlLXNob3dzLXN0YJidXJzdC1zcGlZXItcGF0dGVyb1tYXJzXC83ODc4MTA3NFwvIiwiYWNjb3VudF9pZI6NDM4NDA0LCJhbGVydF9pZI6MTE2NTk5NSwic291cmNlXlkIjo0LCJtZW50a9uX2lkIjoiNzU2NzM5MjMzMIifQ.XH7WJlYkOYTDFysZELmouro__7QVoe5pT9c1qeZw",
    "displayable_url": "usatoday.com\/story\/tech\/nation-now\/2016\/01\/14\/nasa-image-shows-starburst-spider-pattern-mars\/78781074\/",
    "unique_id": "http:\/\/www.usatoday.com\/story\/tech\/nation-now\/2016\/01\/14\/nasa-image-shows-starburst-spider-pattern-mars\/78781074\/",
    "published_at": "2016-01-14T17:16:27.10090700+00:00",
    "created_at": "2016-01-18T16:05:44.0+00:00",
    "country": "US",
    "updated_at": "2016-01-18T16:05:45.0+00:00",
    "favorite": false,
    "folder": "inbox",
    "folder_set_by_user": false,
    "read": false,
    "tone": 0,
    "source_type": "news",
    "source_name": "USA TODAY",
    "source_url": "http:\/\/www.usatoday.com\/",
    "language_code": "en",
    "tasks": [

    ],
    "logs": [

    ],
    "children": {
        "children": [
            { ... mention ... },
            { ... mention ... },
            { ... mention ... },
        ],
        "total": 42,
        "_links": {
            "more": {
                "href": "/api/accounts/THE_ACCOUNT_ID/alerts/112233/mentions/527849937/children?limit=20&before_date=2014-03-20T18:10:37.53829200+00:00",
                "params": {
                    "limit": 20,
                    "before_date": "2014-03-20T18:10:37.53829200+00:00"
                }
            }
        }
    },
    "picture_url": "\/\/t3.gstatic.com\/images?q=tbn:ANd9GcQlW3QxiNh2YxxacyF0gR636ViYH6YS_0ONIRj9pf4OhiRZ8hHHyCQqdOYVgMuToZ1Iixhy",
    "tags": [],
    "offsets": {
        "title": [
            0,
            0,
            4,
            4,
            47,
            47,
            4,
            4
        ],
        "description": [
            10,
            10,
            4,
            4,
            57,
            57,
            4,
            4,
            72,
            72,
            4,
            4,
            79,
            79,
            4,
            4,
            161,
            161,
            4,
            4,
            223,
            223,
            4,
            4
        ],
        "url": [

        ],
        "source_name": [

        ],
        "source_url": [

        ]
    },
    "permissions": {
        "favorite": true,
        "change_folder": true,
        "create_task": true
    },
    "author_influence": {
        "id": "3153793048",
        "alert_id": 112233,
        "kind": "web",
        "url": "http:\/\/www.usatoday.com",
        "name": "usatoday.com",
        "score": 83,
        "scored_id": "usatoday.com"
    },
    "metadata": {
        "twitter": {
            "id_str": "800747234652340224",
            "user": {
                "id_str": "188302352"
            }
        }
    }
}

Twitter Restrictions

For Twitter mentions, the following attributes are not provided: title, description, description_medium, description_short, source_name, source_url, picture_url.

It is still possible to obtain this metadata by using the Twitter API directly, see this guide for more information.

Note that these restrictions apply only to programmatic accesses to the API, so the attributes are still available in CSV or Excel exports, or in the application itself.

Facebook and Instagram Restrictions

For Facebook and Instagram mentions, the following attributes are not provided: title, description, description_medium, description_short, source_name, source_url, picture_url.

We still provide the id of the post on the social network, but cannot provide a sustainable alternative to fetch the posts details from Facebook or Instagram APIs.

Note that these restrictions apply only to programmatic accesses to the API, so the attributes are still available in CSV or Excel exports, or in the application itself.

Original url

original_url

This is the original url of the mention. It can be used for automated lookups.

Clickable url

clickable_url

This is the url that should be used in the context of user interaction, that is, if this is not looked up by a bot, but by a human.

Displayable url

displayable_url

This is the url that should be displayed to users.

Children

children

It indicates if the mention has other related mention, that is, some kind of "duplicate" content. For instance, if the mention is a tweet, children would gather all retweets. Return a maximum of 3 children mentions. You can fetch all mention children.

Offsets

offsets

It is a list of all occurrences of keywords inside the mention. It lists the mention attributes where if may have found such occurrences:

...
"offsets":{
    "title":[...],
    "description":[...],
    ...
},
...

Inside these attributes, it indicates the exact position of the keyword(s). This is for instance used by our web app in order to highlight the characters matching keywords.

In this list, each multiple of 4 corresponds to a single keyword:

  1. offset in characters
  2. offset in utf-16 code units
  3. length in characters
  4. length in utf-16 code units

Example: Assume that the single keyword of your alert is NASA.

...
"offsets":{
    "description": [5, 5, 4, 4, 12, 12, 4, 4],
    ...
},
...

In the above, you have the information that NASA was found twice in the mention description:

  • once from character 5 to character 9 (start: 5, length:4)
  • once from character 12 to character 16 (start: 12, length: 4)

You should use utf-16 code units values if your language does not handle surrogates properly (e.g. if it counts characters like 𝒜 as two characters).

Permissions

permissions

A list of permissions of the current user for that mention.

Author influence

author_influence

Information about author (origin) of the mention, and its influence. To know more about authors, check the author section.

Metadata

metadata

This attribute contains source-specific informations.

Right now, only Twitter mentions have this attribute, and it contains the following attributes:

  • twitter.id_str: The ID of the tweet
  • twitter.user.id_str: The ID of the tweet's author

See this guide for fetching the full original Tweet.