Create a Data Explorer query with the API
This how-to guide explains how to create a Data Explorer query using the Discourse API.
Required user level: Administrator
Prerequisites
Before you begin, ensure you have:
- The Data Explorer plugin installed and enabled on your site
- An API key with Global scope, associated with an admin user (see Create and configure an API key)
Creating queries requires a global API key. The granular “run queries” scope only allows running existing queries, not creating new ones.
Create a query
To create a new Data Explorer query, make a POST request to /admin/plugins/discourse-data-explorer/queries.
Parameters
| Parameter | Required | Description |
|---|---|---|
query[name] |
Yes | The name for your query |
query[sql] |
Yes | The SQL statement to execute |
query[description] |
No | A description of what the query does |
query[group_ids] |
No | Array of group IDs that can access this query |
Example request
curl -X POST "https://your-site.com/admin/plugins/discourse-data-explorer/queries" \
-H "Content-Type: multipart/form-data;" \
-H "Api-Key: <api-key>" \
-H "Api-Username: <username>" \
-F 'query[name]=User count query' \
-F 'query[sql]=SELECT COUNT(*) FROM users'
Example response
{
"query": {
"id": 49,
"name": "User count query",
"description": null,
"username": "<username>",
"group_ids": [],
"last_run_at": "2025-03-13T18:41:44.226Z",
"user_id": 1,
"is_default": false,
"sql": "SELECT COUNT(*) FROM users",
"param_info": [],
"created_at": "2025-03-13T18:41:44.226Z",
"hidden": false
}
}
Note the id value in the response, you’ll need this to run the query. For details on running queries via the API, see Run Data Explorer queries with the Discourse API.
Last edited by @MarkDoerr 2026-02-25T00:36:21Z
Last checked by @MarkDoerr 2026-01-26T23:29:25Z
Check document
Perform check on document: