Gameplainer.com helps you monitor mentions of your brand or product across popular social platforms, including Reddit, BlueSky, X (formerly Twitter), YouTube, and Google Alerts.
With the Gameplainer API, you can seamlessly access these mentions via web requests, making it easy to integrate real-time brand monitoring into your custom dashboards, analytics tools, customer support systems, or any other application.
Getting started
- Sign up to Gameplainer, and subscribe to a
Premiumaccount Go to your user settings page, and scroll down to API Key settings, and click the “Generate API Key” button
API Key settings - push the button to get an API key
Once you’ve created an API Key, it will be displayed on the page
API Key settings - displaying an API Key
Click “Copy” and it’ll be copied to your clipboard
Reference
Basics
All queries need a valid API Key, which must be passed as a header parameter as shown in the examples for each of the end points.
Date formats
Any start_date or end_date parameter accepts either of:
- Unix epoch seconds, eg
1733666480(2024-12-08 14:01:17 UTC). - A date or datetime string, eg
2024-12-08or2024-12-08T14:01:17Z.
Strings that include a timezone offset (a trailing Z or +02:00) are honored as written. A string with no offset is interpreted as UTC, so include an offset if you need a specific zone.
If a date parameter is present but cannot be read as either form, the request returns an error instead of silently ignoring the filter. For example, {"success": false, "error": "start_date must be a unix timestamp (seconds, post-2024) or a parseable date"}. Epoch values must be after 2024-01-01.
Endpoint: Query/List
Returns all of your searches. Optionally filter to a single source type.
https://gameplainer.com/api/query/list
Parameters
| Name | Required | Values | Description |
|---|---|---|---|
| type | optional | reddit, twitter, youtube, bluesky, google_alert, steam, twitch |
If specified, only searches of that source are returned. x is accepted as an alias for twitter |
Example use
All of your searches:
curl -X GET "https://gameplainer.com/api/query/list" \ -H "Authorization: YOUR_API_KEY"
Only your Twitch searches:
curl -X GET "https://gameplainer.com/api/query/list?type=twitch" \ -H "Authorization: YOUR_API_KEY"
Example response
{
"success": true,
"data": [
{
"id": "vPt3Or",
"type": "reddit",
"description": "SubReddit: 'indiegames' searching for `twister`",
"frequency": "hour",
"results_total": 19,
"last_searched": 1733692122,
"search": "twister",
"reddit_search_type": "comments",
"mute_subreddits": "noisysubbredditexample, freeindiegames",
"subreddits": null
},
{
"id": "KqtWmJ",
"type": "youtube",
"description": "YouTube videos matching `twister`",
"frequency": "hour",
"results_total": 110,
"last_searched": 1733692120,
"search": "twister",
"followers_filter": 1000
},
{
"id": "X1t1XA",
"type": "twitch",
"description": "Twitch streams of Twister",
"frequency": "minute",
"results_total": 8121,
"last_searched": 1768409143
}]
}
Endpoint: Query/Search
Returns a JSON object containing results matching your searches, newest first.
Results are cursor-paginated. Every response includes a meta object with the cursors for the current page, so you can page backwards through history or poll forward for new results without tracking offsets.
https://gameplainer.com/api/query/search
Parameters
| Name | Required | Values | Description |
|---|---|---|---|
| type | optional | reddit, twitter, youtube, bluesky, google_alert, steam |
If not specified, results are not filtered by source. |
| forum_id | optional | a forum hash key, eg vPt3Or |
The id of one of your searches (as returned by Query/List). Restricts results to that single source/channel. Must be a search belonging to your account. |
| start_date | optional | Unix epoch seconds (eg 1733666480) or a date/datetime string (eg 2024-12-08 or 2024-12-08T14:01:17Z). See Date formats. |
If specified, only results found by Gameplainer at or after this time are returned. A present-but-invalid value returns an error. |
| end_date | optional | Unix epoch seconds (eg 1733666480) or a date/datetime string (eg 2024-12-08 or 2024-12-08T14:01:17Z). See Date formats. |
If specified, only results found by Gameplainer at or before this time are returned. A present-but-invalid value returns an error. |
| start_after | optional | a result hash key, eg KaMiZG |
Returns results OLDER than this result. Pass the meta.cursor_bottom from your previous response to fetch the next (older) page. Only valid with sort=recent. |
| start_before | optional | a result hash key, eg Gxi0WE |
Returns results NEWER than this result. Pass the meta.cursor_top from your most recent response to fetch results that have arrived since. Only valid with sort=recent. |
| sort | optional | recent (default), likes, replies, reposts, quotes, bookmarks, views, engagement |
Ordering. recent returns newest first with cursor paging. Any other value ranks by that engagement metric, highest first, and uses page-based paging (see Sorting by engagement). |
| page | optional | an integer 1 or greater |
Page number for engagement sorts. Defaults to 1. Ignored when sort=recent. |
| num_per_page | optional | an integer between 1 and 50 |
If specified, only this many items will be returned per query. By default this will be 50 |
Paging through results
Each response includes a meta block:
| Field | Description |
|---|---|
| count | Number of results in this page |
| cursor_top | Hash key of the newest result in this page |
| cursor_bottom | Hash key of the oldest result in this page |
| has_more | true if more results exist in the direction you paged |
| last_searched | Unix timestamp of when the source was last checked. Only returned when forum_id is supplied. |
To walk backwards through history, repeat the request passing start_after=<cursor_bottom> until has_more is false. To poll for new results, store cursor_top and pass it as start_before on your next call.
Engagement metrics
Where a source exposes per-result engagement, the result includes a metrics object. This is how you rank X (Twitter) posts by engagement.
| Field | Description |
|---|---|
| likes | Like count |
| replies | Reply count. On X this is what the platform shows as comments. |
| reposts | Repost / retweet count |
| quotes | Quote-post count |
| bookmarks | Bookmark count |
| views | View count |
| updated_at | ISO8601 datetime (UTC) of the last time these counts were refreshed, or null if they have only the value captured when the post was first found |
The metrics object is only present when at least one metric is available, so check for its presence before reading it. For X results the top-level rating and comments fields are intentionally null; engagement lives in metrics. Counts are captured when a post is first found and best-effort refreshed afterwards, so recent posts may still have their counts climbing; updated_at tells you how fresh they are.
Sorting by engagement
By default results come back newest first. Pass sort to rank by engagement instead, highest first. This is the simplest way to pull the top posts for a weekly report.
| sort value | Ranks by |
|---|---|
| recent | Newest first (default). Uses cursor paging. |
| likes | Like count |
| replies | Reply count |
| reposts | Repost / retweet count |
| quotes | Quote-post count |
| bookmarks | Bookmark count |
| views | View count |
| engagement | Composite: likes + reposts + quotes + replies |
Engagement sorts use page-based paging rather than cursors. Combine sort with start_date / end_date to bound the window, set num_per_page (up to 50), and walk with page (1, 2, 3, ...) until has_more is false. The cursor parameters start_after and start_before are only valid with sort=recent; passing them alongside a different sort returns an error.
The response meta for an engagement sort returns count, sort, page, and has_more (no cursor_top / cursor_bottom). Posts with no value for the chosen metric sort last. Because counts are refreshed on a best-effort basis, rankings of very recent posts can still shift slightly as their numbers settle.
Example: top X posts of the week by engagement
curl -X GET "https://gameplainer.com/api/query/search?type=twitter&start_date=2024-12-02&end_date=2024-12-08T23:59:59Z&sort=engagement&num_per_page=25" \ -H "Authorization: YOUR_API_KEY"
The second page:
curl -X GET "https://gameplainer.com/api/query/search?type=twitter&start_date=2024-12-02&end_date=2024-12-08T23:59:59Z&sort=engagement&num_per_page=25&page=2" \ -H "Authorization: YOUR_API_KEY"
Example use
Most recent results across all your searches:
curl -X GET "https://gameplainer.com/api/query/search" \ -H "Authorization: YOUR_API_KEY"
Results for a single search/channel, 25 at a time:
curl -X GET "https://gameplainer.com/api/query/search?forum_id=vPt3Or&num_per_page=25" \ -H "Authorization: YOUR_API_KEY"
The next (older) page:
curl -X GET "https://gameplainer.com/api/query/search?forum_id=vPt3Or&num_per_page=25&start_after=XPipEp" \ -H "Authorization: YOUR_API_KEY"
Results within a date window, using a date string:
curl -X GET "https://gameplainer.com/api/query/search?forum_id=vPt3Or&start_date=2024-12-01&end_date=2024-12-08T23:59:59Z" \ -H "Authorization: YOUR_API_KEY"
Example response
{
"success": true,
"data": [
{
"id": "Gxi0WE",
"datetime": "2024-12-09T08:26:18.571Z",
"source": "bluesky",
"source_id": "at://did:plc:lzwscnvcbkpdytcjvsixfyar/app.bsky.feed.post/3lcucjahwck2x",
"sub_type": null,
"search": "twister",
"url": "https://bsky.app/profile/chrisvasselli.bsky.social/post/3lcucjahwck2x",
"user_name": "chrisvasselli.bsky.social",
"title": "Post",
"body": "Things I learned at the Nintendo Museum today: Nintendo published Twister in Japan.",
"rating": null,
"comments": "1",
"followers": "950",
"language": null,
"nsfw": null,
"image_thumbnail_url": null
},
{
"id": "XPipEp",
"datetime": "2024-12-08T08:00:39.000Z",
"source": "twitter",
"source_id": "1865700000000000000",
"sub_type": "tweet",
"search": "twister",
"url": "https://twitter.com/somegamer/status/1865700000000000000",
"user_name": "somegamer",
"title": "Tweet",
"body": "just hit a new personal best on Twister, this game lives in my head rent free",
"rating": null,
"comments": null,
"followers": "4820",
"language": "en",
"nsfw": null,
"image_thumbnail_url": null,
"metrics": {
"likes": 312,
"replies": 18,
"reposts": 26,
"quotes": 4,
"bookmarks": 41,
"views": 20544,
"updated_at": "2024-12-08T20:13:20.000Z"
}
}
],
"meta": {
"count": 2,
"cursor_top": "Gxi0WE",
"cursor_bottom": "XPipEp",
"has_more": true,
"last_searched": 1733692122
}
}
{"success": false, "error":"Invalid API key"}
Endpoint: Query/Streams
Returns Twitch stream sessions for one of your games, newest first.
A game is identified either by app_id (a game hash key) or by forum_id (one of your searches, resolved to its game). You can only request streams for games you track. Results are cursor-paginated using the same scheme as Query/Search.
https://gameplainer.com/api/query/streams
Parameters
| Name | Required | Values | Description |
|---|---|---|---|
| app_id | Required (or forum_id) | a game hash key, eg Qd3R8x |
A game hash key. Returns streams for that game. |
| forum_id | Required (or app_id) | a forum hash key, eg vPt3Or |
The id of one of your searches (from Query/List). Resolved to the game it tracks. |
| live | optional | true, false |
If true, only currently-live streams (no end time) are returned. |
| start_date | optional | Unix epoch seconds (eg 1733666480) or a date/datetime string (eg 2024-12-08 or 2024-12-08T14:01:17Z). See Date formats. |
If specified, only streams that started at or after this time are returned. A present-but-invalid value returns an error. |
| end_date | optional | Unix epoch seconds (eg 1733666480) or a date/datetime string (eg 2024-12-08 or 2024-12-08T14:01:17Z). See Date formats. |
If specified, only streams that started at or before this time are returned. A present-but-invalid value returns an error. |
| start_after | optional | a stream hash key, eg KaMiZG |
Returns streams OLDER than this one. Pass the meta.cursor_bottom from your previous response to fetch the next page. |
| start_before | optional | a stream hash key, eg Gxi0WE |
Returns streams NEWER than this one. Pass the meta.cursor_top from your most recent response to fetch streams added since. |
| num_per_page | optional | an integer between 1 and 50 |
Items per page. Defaults to 50. |
Paging through results
Each response includes a meta block:
| Field | Description |
|---|---|
| count | Number of streams in this page |
| cursor_top | Hash key of the newest stream in this page |
| cursor_bottom | Hash key of the oldest stream in this page |
| has_more | true if more streams exist in the direction you paged |
| game | The game these streams belong to: app_id and name |
To walk backwards through history, repeat the request passing start_after=<cursor_bottom> until has_more is false. To poll for new streams, store cursor_top and pass it as start_before on your next call.
Example use
Recent streams for a game, by game hash key:
curl -X GET "https://gameplainer.com/api/query/streams?app_id=Qd3R8x&num_per_page=25" \ -H "Authorization: YOUR_API_KEY"
Recent streams for the game tracked by one of your searches:
curl -X GET "https://gameplainer.com/api/query/streams?forum_id=vPt3Or" \ -H "Authorization: YOUR_API_KEY"
Only currently-live streams:
curl -X GET "https://gameplainer.com/api/query/streams?app_id=Qd3R8x&live=true" \ -H "Authorization: YOUR_API_KEY"
Example response
{
"success": true,
"data": [
{
"id": "Gxi0WE",
"live": false,
"start_time": "2024-12-09T18:02:11.000Z",
"end_time": "2024-12-09T20:24:53.000Z",
"duration_minutes": 142,
"peak_viewers": 1820,
"current_viewers": 0,
"title": "twister speedrun attempts!",
"language": "en",
"is_mature": false,
"thumbnail_url": "https://static-cdn.jtvnw.net/.../thumb.jpg",
"helix_stream_id": "40987654321",
"streamer": {
"name": "SomeStreamer",
"login": "somestreamer",
"twitch_id": "123456789",
"followers": 95000,
"profile_image_url": "https://static-cdn.jtvnw.net/.../profile.png"
}
},
{
"id": "XPipEp",
"live": true,
"start_time": "2024-12-09T16:45:00.000Z",
"end_time": null,
"duration_minutes": 73,
"peak_viewers": 540,
"current_viewers": 512,
"title": "chill twister run",
"language": "en",
"is_mature": false,
"thumbnail_url": "https://static-cdn.jtvnw.net/.../thumb2.jpg",
"helix_stream_id": "40987654399",
"streamer": {
"name": "AnotherStreamer",
"login": "anotherstreamer",
"twitch_id": "987654321",
"followers": 12000,
"profile_image_url": "https://static-cdn.jtvnw.net/.../profile2.png"
}
}
],
"meta": {
"count": 2,
"cursor_top": "Gxi0WE",
"cursor_bottom": "XPipEp",
"has_more": true,
"game": {
"app_id": "Qd3R8x",
"name": "Twister"
}
}
}
{"success": false, "error":"game not found or not accessible"}
Endpoint: Query/Create
Create a new search for Gameplainer to find mentions on a variety of sources, including Twitter (X), BlueSky, and Reddit.
Each search is limited to one source, so if you want to create multiple sources, you'll need to create multiple searches.
Searches are processed by Gameplainer at a frequency based on your account level.
https://gameplainer.com/api/query/create
Parameters
| Name | Required | Values | Description |
|---|---|---|---|
| type | Required | reddit, twitter, youtube, bluesky, google_alert |
|
| search | Required | string value, maximum 400 characters | |
| follower_filter | optional | Integer, greater than 0 | |
| frequency | optional | minute, hour, day | |
| search_mentions | optional | true, false |
Used for Twitter/X searches: if specified, the value in search will be used as a username, and the returned data from the query will be mentions of that username |
| exact_search_required | optional | true, false |
Used for Twitter/X searches. If specified, exact string literals will be needed in tweets |
| reddit_search_type | Required if type reddit, otherwise not used | posts, comments |
|
| mute_subreddits | optional | comma separated list of subreddits without the r/ prefix | |
| subreddits | optional | comma separated list of subreddits without the r/ prefix |
Example use
curl -X GET "https://gameplainer.com/api/query/create?type=reddit&reddit_search_type=posts&search=twister" \ -H "Authorization: YOUR_API_KEY"
curl -X GET "https://gameplainer.com/api/query/create?type=google_alert&search=https%3A%2F%2Fwww.google.com%2Falerts%2Ffeeds%2F16311364085116075549%2F11892934012420830009" \ -H "Authorization: YOUR_API_KEY"
Example Response
{
"success": true,
"data": [
{
"id": "12tdYL",
"type": "reddit",
"search": "twister",
"followers_filter": 30,
"frequency": "hour",
"search_mentions": false,
"exact_search_required": null,
"reddit_search_type": "new",
"mute_subreddits": null,
"subreddits": null,
"results_total": 0,
"last_searched": null
}]
}
{"success": false, "error":"Invalid API key"}
Stay in the loop
Get notified when we publish new articles on game development and player feedback.
