---
title: "Run an Insights query"
method: POST
path: "/projects/{project_id}/insights/queries"
tags: ["Insights"]
---

# Run an Insights query

`POST /projects/{project_id}/insights/queries`

## Request

- Base URL: `https://app.honeybadger.io/v3`
- URL: `https://app.honeybadger.io/v3/projects/{project_id}/insights/queries`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/honeybadger/apis/honeybadger-api/docs/projects/:project_id/insights/queries/post.ts> (a function with typed inputs; its response is checked against the schema)

Runs a BadgerQL query against the project's event streams and returns the result. It's a POST, but it changes nothing.

Pass `stream_ids` to choose streams, or leave it out to search them all. Events on a stream that isn't selected return no rows. See [BadgerQL](https://docs.honeybadger.io/guides/insights/badgerql/) for the query language.

## Path parameters

- `project_id` string, required

## Request body

- object
  - `query` string, required: BadgerQL query
  - `stream_ids` string[]: Streams to search. Omit it, or pass an empty array, to search every stream on the project. Every ID must belong to this project; repeated IDs are deduplicated.
  - `ts` string: Time range for the query
  - `timezone` string: Timezone for time bucketing and display

## Response `200`

The query result. Its fields depend on the query: an aggregation returns different fields from an event listing.

`links.web` opens this query in the Honeybadger web UI, with the request's `ts`, `stream_ids` and `timezone` (UTC when none was sent). Present even when `data` carries an `error` from a query that failed while running.

- object
  - `data` object, required: The query result; its fields depend on the query.
  - `links` WebLinks, required: Links into the Honeybadger web UI
    - `web` string, uri, required: The resource's page in the Honeybadger web UI, as an absolute URL. Resources without a page, such as outages and deploys, don't have `links`. For a project provisioned through Heroku, error, notice and comment links go through Heroku's single sign-on.
  - `meta` ResponseMeta
    - `request_id` string: Unique identifier for the request, for correlating with support

## Other responses

- `401`: The credential is missing, invalid, expired or revoked (`unauthorized`), or was sent in a way v3 doesn't accept (see the examples).
- `403`: The credential isn't allowed to do this. `error.code` says why. An account or project the credential doesn't cover is 404 `not_found`, not 403.
- `404`: Resource not found
- `422`: The query was rejected. For a syntax or semantic error, `error.message` explains it and `error` may carry more keys. Also returned when `query` is missing or not a string, when `stream_ids` isn't an array of strings, or when a stream ID isn't one of the project's.
- `429`: Rate limit exceeded. The limit is per credential owner per hour: a person's tokens share one budget, and an account token uses the account's. Wait `Retry-After` seconds and retry.
- `503`: Insights didn't answer. Retry.

---

[API](https://skmtc.dev/honeybadger/apis/honeybadger-api.md) - [All operations](https://skmtc.dev/honeybadger/apis/honeybadger-api/llms.txt) - [OpenAPI document](https://skmtc.dev/honeybadger/apis/honeybadger-api/revisions/cbcff53f2c8a?raw)