/api/v1/mentions
List mentions
/api/v1/mentions
List mentions
Endpoint
- Method:
GET - Path:
/api/v1/mentions
Base URL
https://api.mentionkit.com
Authentication
Use Authorization: Bearer YOUR_API_KEY.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| sort | query | No | string (newest, oldest) | Sort order for results. |
| cursor | query | No | integer | Use this for pagination (pass the previous nextCursor value). |
| limit | query | No | integer | Maximum mentions to return. Values above 250 are capped at 250. |
| projectId | query | No | integer | Filter by one project ID. |
| category | query | No | string (brand, industryinsights, competitorkeywords) | Filter by keyword category. |
| platform | query | No | string | Filter by platform (reddit, x, twitter, linkedin, hn, hackernews, youtube, yt, bluesky, bsky, tiktok, medium, github, or slack). |
| score | query | No | string | Comma-separated mention scores. Use 1 for high score, 0 for low score, or 0,1 for both. Both scores are returned by default. |
| keywords | query | No | string | Comma-separated keywords, e.g. mentionkit,social listening. |
| tags | query | No | string | Comma-separated mention tags, e.g. insight,alternatives (allowed: positive, negative, comparing, alternatives, promotional, insight, ai-slop). Matches any selected tag. |
| startdate | query | No | string | Start date (inclusive) in YYYY-MM-DD format. Filters by sourceCreatedAt. |
| enddate | query | No | string | End date (inclusive) in YYYY-MM-DD format. Filters by sourceCreatedAt. |
Responses
200: Mentions fetched successfully.
- Content-Type:
application/json - Schema:
MentionListResponse - Example:
{
"items": [
{
"id": 2001,
"platform": "REDDIT",
"keywordValue": "example alternative",
"projectId": 3001,
"trackerId": null,
"subreddit": "saas",
"authorHandle": "user_123",
"text": "Looking for alternatives to ExampleMonitor for social listening.",
"lang": "en",
"sourceCreatedAt": "2026-03-20T10:15:00.000Z",
"createdAt": "2026-03-20T10:15:02.000Z",
"sourceUrl": "https://www.reddit.com/r/saas/comments/p_abc123/",
"score": 1,
"reason": "Someone is looking for alternatives to their current monitoring tool.",
"angle": "Share a practical way to compare monitoring tools.",
"engagement": {
"likes": 4,
"comments": 2
},
"communityId": null,
"communityName": null,
"tags": ["alternatives"],
"commentStatus": 1,
"projectName": "Example Project",
"platformPostId": "p_abc123",
"permalink": "https://www.reddit.com/r/saas/comments/p_abc123/",
"redditPostId": "rp_abc123",
"redditCommentId": "rc_def456"
}
],
"nextCursor": null,
"limit": 50,
"sort": "newest",
"project": null
}401: Missing or invalid API key.
- Content-Type:
application/json - Schema:
ErrorResponse - Example:
{
"error": "Invalid API key"
}403: API access blocked. The organization is deactivated for API usage and must have an active trial, active paid subscription, or billing exemption.
- Content-Type:
application/json - Schema:
ErrorResponse - Example:
{
"error": "API access requires a trial, paid subscription, or billing exemption"
}500: Unexpected server error.
- Content-Type:
application/json - Schema:
ErrorResponse
Error codes
401: Missing or invalid API key.403: API access blocked. The organization is deactivated for API usage and must have an active trial, active paid subscription, or billing exemption.500: Unexpected server error.
