Fetch a mention

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

Get a single mention by its ID.

Parameters

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

Page content

Minimal curl example

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

Request example

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

None

Response example

  • Body
{
    "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.