Mentions API

Retrieve collected social-media content for one project keyword.

Endpoint: GET /api/mentions

Authentication: Bearer token

Authorization: Bearer <access_token>

Get mentions

GET /api/mentions

Return a paginated list of mentions with optional source and sentiment filters.

Query parameters

Parameter	Type	Required	Default	Description
keywordId	string	Yes	—	Keyword ID; the current app flow uses project data.id, but Swagger does not formally define that mapping
page	integer	No	1	Page number
limit	integer	No	10	Items per page; maximum 100
sentimen	integer	No	—	Sentiment filter: 1, 0, or -1
sosmedId	string	No	—	Social-media source ID filter

Supported sosmedId values:

• twitter
• facebook
• youtube
• tiktok
• instagram
• news

Success response

200 OK:

{
  "data": [
    {
      "id": "mention_id",
      "targeted_account_id": "account_id",
      "content": "A post that matched the monitored keyword.",
      "keywordid": "project_or_keyword_id",
      "url": "https://social.example/posts/123",
      "sentimen": 1,
      "socialmediaid": "social_media_id",
      "createdat": "2026-07-20T08:30:00Z",
      "updated_at": "2026-07-20T08:35:00Z",
      "targeted_account": {
        "username": "account_username",
        "display_name": "Account Name"
      },
      "SnaKeyword": {
        "group": "Acme July Monitoring",
        "keyword": "acme"
      }
    }
  ],
  "total": 43,
  "page": 1,
  "limit": 10,
  "totalPages": 5
}

Response fields

Field	Description
data	Mention objects for the requested page
total	Total matching mentions
page	Current page number
limit	Requested page size
totalPages	Total number of pages
data[].keywordid	Keyword identifier associated with the mention
data[].sentimen	Numeric sentiment value: 1, 0, or -1
data[].socialmediaid	Source social-media identifier
data[].targeted_account	Author account information
data[].SnaKeyword	Project group and matched keyword

The capitalized response key SnaKeyword is intentional and matches the published schema.

Declared responses

Status	Meaning
200	Mentions retrieved successfully
400	keywordId is missing
500	Internal server error

The endpoint requires bearer authentication, although Swagger does not explicitly include 401 in this operation's response table.

cURL

curl \
  "$SOCIOVITE_API_URL/api/mentions?keywordId=project_or_keyword_id&page=1&limit=10" \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <access_token>'

Add filters only when needed:

curl \
  "$SOCIOVITE_API_URL/api/mentions?keywordId=project_or_keyword_id&page=1&limit=10&sentimen=1&sosmedId=social_media_id" \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <access_token>'

Get mentions with Model R10

GET /api/mentions/r10

Retrieve paginated mentions using the Model R10 engine. This endpoint supports sentiment filtering and filtering by one or more social-media sources.

Model R10 endpoint

/api/mentions/r10 is separate from /api/mentions. On the R10 endpoint, sosmedId accepts a comma-separated list such as twitter,news; do not send it as a JSON array.

The supplied R10 contract references web.TargetedAccountContentsModelR10Response for a successful response but does not include that model's definition. The exact response fields are therefore not inferred here.

Query parameters

Parameter	Type	Required	Default	Constraints and description
keywordId	string	Yes	—	Keyword ID in UUID or CUID format
page	integer	No	1	Page number; minimum 1
limit	integer	No	10	Items per page; minimum 1, maximum 100
sentimen	integer	No	—	Sentiment filter: -1 negative, 0 neutral, 1 positive
sosmedId	string	No	—	Comma-separated sources: twitter, tiktok, facebook, youtube, instagram, news

Declared responses

Status	Meaning
200	Mentions retrieved successfully
400	Invalid request parameters
401	Unauthorized
403	Forbidden
406	Unsupported Accept header
500	Internal server error

cURL

Retrieve the first page without optional filters:

curl \
  "$SOCIOVITE_API_URL/api/mentions/r10?keywordId=keyword_id&page=1&limit=10" \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <access_token>'

Filter positive mentions from Twitter and news:

curl \
  "$SOCIOVITE_API_URL/api/mentions/r10?keywordId=keyword_id&page=1&limit=10&sentimen=1&sosmedId=twitter,news" \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <access_token>'

Error shape

{
  "success": false,
  "error": "Invalid request",
  "message": "keywordId is required"
}