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.
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 | A timestamp in Unix Time integer format (eg 2024-12-08 14:01:17 UTC is 1733666480) |
If specified, only results found by Gameplainer from this time will be returned |
| end_date | optional | A timestamp in Unix Time integer format (eg 2024-12-08 14:01:17 UTC is 1733666480) |
If specified, only results found by Gameplainer until this time will be returned |
| 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. |
| 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. |
| 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.
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"
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": "youtube",
"source_id": "nxRA-qIk160",
"sub_type": null,
"search": "twister",
"url": "http://www.youtube.com/watch?v=nxRA-qIk160",
"user_name": "MrNotBad (1.33M subscribers)",
"title": "We Crafted Cool DIY Automatic Wire Twister",
"body": "",
"rating": null,
"comments": null,
"followers": "1330000",
"language": null,
"nsfw": null,
"image_thumbnail_url": null
}
],
"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 | A timestamp in Unix Time integer format (eg 1733666480) |
If specified, only streams that started at or after this time are returned. |
| end_date | optional | A timestamp in Unix Time integer format (eg 1733666480) |
If specified, only streams that started at or before this time are returned. |
| 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.
