Fetch mentions

GET /accounts/{account_id}/alerts/{alert_id}/mentions

Parameters

  • account_id (string) - Id of the account
  • alert_id (number) - Id of the alert

Page content

Minimal curl example

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

Available properties

Most interesting part of this method is the querystring, where you can apply a range of filters. All filters are optional.

Properties index_version Definition Example
since_id 1+ Return mentions with an id upper (more recently found) than the given id. Returns mentions ordered by id, which corresponds to the order in which they have been found. Can not be combined with before_date, not_before_date, cursor. 52638
before_date 1+ Return mentions published before the provided date. Returns mentinos ordered by publication date. 2011-11-16T19:20:30.12345+01:00
not_before_date 1+ Ignore mentions older than given date (only allowed when before_date if provided) 2011-11-16T19:20:30.12345+01:00
limit 1+ Number of mentions to return (default 20, max 1000). Use a small limit to get faster response times. 20
source 1+ One of available sources. Only available to plans with search access. web
unread 1+ Whether to return only unread mentions. Can not be combined with favorite, q, and tone. 1
favorite 1+ Whether to return only favorite mentions. Can not be combined with folder, when folder is not inbox or archive. 1
folder 1+ Filter by folder. Must be one of inbox, archive, spam, trash. With spam and trash, include_children is enabled by default. archive
tone 1+ Filter by tone. Must be one of -1, 0, 1 for negative, neutral, or positive, respectively. This parameter can take an array of values. 1
countries 1+ Filter by country. This parameter can take an array of values. US
include_children 1+ Whether to include children mentions. 1
sort 1+ Sort results. Must be one of published_at, author_influence.score, direct_reach, cumulative_reach, domain_reach. This parameter is allowed only to plans with search access. author_influence.score
languages 1+ Filter by language. This parameter can take an array of values. en
timezone 1+ Timezone to use when parsing dates from the q parameter. America/New_York
q 1+ Filter by keywords. This parameter is allowed only to plans with search access. nasa source:(facebook OR twitter) in:(inbox OR archive)
cursor 1+ Abstract pagination cursor

Index version

The index_version column in the table above indicates the minimum index_version an alert must have for the filter property to be available. The index version of an alter is available in its index_version attribute.

Pagination

Retrieving older mentions should be done by following the _links.more attribute in the result.

Pulling for new mentions should be done by following the _links.pull attribute in the result. Also consider using the streaming API.

Q parameter

q

The q parameter allows to filter mentions by keyword, or to combine filters that are not otherwise combinable in the query string.

Only accounts with search access can use this parameter.

Example:

source:(facebook OR twitter) in:(inbox OR archive) is:favorite tone:(neutral OR positive) language:en published_at:[2015-12-01 TO 2015-12-31]

Below, the q fields which are available only for index_version superior to 1.

q element index version
is:unread 2+

Request example

  • Headers
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept-Version: 1.19
  • Body

None

Response example

  • Body
{
    "mentions":[
        {...mention...},
        {...mention...},
        ...
    ],
    "_links":{
        "more":{
            "href": "...url to get older mentions..."
        },
        "pull":{
            "href": "...url to get newer mentions..."
        }
    }
}