# Create a Data Explorer query using the API

**URL:** https://meta.discourse.org/t/create-a-data-explorer-query-using-the-api/394388
**Category:** Integrations
**Tags:** data-explorer, rest-api, how-to
**Created:** [January 26, 2026, 11:27pm UTC](https://meta.discourse.org/t/create-a-data-explorer-query-using-the-api/394388 "2026-01-26T23:27:26Z")
**Posts on this page:** 4
**Page:** 1

<div class="post-metadata">

### Author: ![Discourse](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/discourse/32/148734_2.png) [@Discourse](https://meta.discourse.org/u/Discourse)
#### Post date: [January 26, 2026, 11:27pm UTC](https://meta.discourse.org/t/create-a-data-explorer-query-using-the-api/394388/1 "2026-01-26T23:27:26Z")

</div>

# Create a [Data Explorer](https://meta.discourse.org/t/32566?silent=true) query with the API

> 🔖 This how-to guide explains how to create a [Data Explorer](https://meta.discourse.org/t/32566) query using the Discourse API.
> 
> 🙋 Required user level: Administrator

## Prerequisites

Before you begin, ensure you have:

- The [Data Explorer](https://meta.discourse.org/t/32566) 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](https://meta.discourse.org/t/230124))

> ℹ 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](https://meta.discourse.org/t/32566?silent=true) 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

```bash
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

```json
{
  "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](https://meta.discourse.org/t/120063).

> Last edited by @MarkDoerr 2026-02-25T00:36:21Z
> 
> Last checked by @MarkDoerr 2026-01-26T23:29:25Z
> 
> > **Check document**
> >
> > Perform check on document:

---

<div class="post-metadata">

### Author: ![pfaffman](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/pfaffman/32/120154_2.png) [@pfaffman](https://meta.discourse.org/u/pfaffman)
#### Post date: [February 25, 2026, 3:54pm UTC](https://meta.discourse.org/t/create-a-data-explorer-query-using-the-api/394388/2 "2026-02-25T15:54:37Z")

</div>

> [@Discourse](#):
>
> To create a new [Data Explorer](https://meta.discourse.org/t/32566?silent=true) query, make a `POST` request to `/admin/plugins/discourse-data-explorer/queries`.

You changed the path of the API call and broke my query!?! it used to be `/admin/plugins/explorer/queries/3/run` and all of a sudden the github action started failing. This doesn’t seem very nice.

---

<div class="post-metadata">

### Author: ![murphyke](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/murphyke/32/184302_2.png) [@murphyke](https://meta.discourse.org/u/murphyke)
#### Post date: [March 24, 2026, 4:06pm UTC](https://meta.discourse.org/t/create-a-data-explorer-query-using-the-api/394388/3 "2026-03-24T16:06:55Z")

</div>

Our tooling broke because of that path change and also the change to require a Global API key instead of a Read-only API key, which used to be sufficient.

---

<div class="post-metadata">

### Author: ![pfaffman](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/pfaffman/32/120154_2.png) [@pfaffman](https://meta.discourse.org/u/pfaffman)
#### Post date: [March 29, 2026, 7:46pm UTC](https://meta.discourse.org/t/create-a-data-explorer-query-using-the-api/394388/4 "2026-03-29T19:46:03Z")

</div>

> [@murphyke](#):
>
> Our tooling broke because of that path change

That was annoying.

> [@murphyke](#):
>
> also the change to require a Global API key instead of a Read-only API key, which used to be sufficient.

That sounds like a bug.