# Create query range

URL: https://docs.hanzo.ai/docs/openapi/o11y/post-o11y-query-range

> Executes a composite query over a time range: builder queries over traces, logs and metrics, formulas, trace operators, PromQL and Datastore SQL, answering time series, scalars or raw records as the request type asks.

`POST /v1/o11y/query_range`

> [O11y →](https://docs.hanzo.ai/docs/openapi/o11y) · [All API references →](https://docs.hanzo.ai/docs/openapi) · [Get started →](https://docs.hanzo.ai/docs/guides)

|               |                                            |
| ------------- | ------------------------------------------ |
| **Address**   | `https://api.hanzo.ai/v1/o11y/query_range` |
| **Method**    | `POST`                                     |
| **Operation** | `post_o11y_query_range`                    |
| **Auth**      | `Authorization: Bearer $HANZO_API_KEY`     |

Executes a composite query over a time range: builder
queries over traces, logs and metrics, formulas, trace operators, PromQL and
Datastore SQL, answering time series, scalars or raw records as the request
type asks.

Callers need the viewer role; the runtime's own gate enforces it.

## Request

16 fields, body `application/json` (required).

| Field                                  | In   | Type                  | Required | Description                                                                |
| -------------------------------------- | ---- | --------------------- | -------- | -------------------------------------------------------------------------- |
| `compositeQuery`                       | body | o11y.CompositeQuery   | —        |                                                                            |
| `compositeQuery.queries`               | body | o11y.QueryEnvelope\[] | —        | Queries is the queries to use for the request.                             |
| `compositeQuery.queries[].spec`        | body | any                   | —        | Spec is the deferred decoding of the query if any.                         |
| `compositeQuery.queries[].type`        | body | any                   | —        | Type is the type of the query.                                             |
| `end`                                  | body | integer (uint64)      | —        | End is the end time of the query in epoch milliseconds.                    |
| `formatOptions`                        | body | o11y.FormatOptions    | —        |                                                                            |
| `formatOptions.fillGaps`               | body | boolean               | —        |                                                                            |
| `formatOptions.formatTableResultForUI` | body | boolean               | —        |                                                                            |
| `noCache`                              | body | boolean               | —        | NoCache is a flag to disable caching for the request.                      |
| `requestType`                          | body | any                   | —        | RequestType is the type of the request.                                    |
| `schemaVersion`                        | body | string                | —        | SchemaVersion is the version of the schema to use for the request payload. |
| `start`                                | body | integer (uint64)      | —        | Start is the start time of the query in epoch milliseconds.                |
| `variables`                            | body | object                | —        | Variables is the variables to use for the request.                         |
| `variables.*`                          | body | o11y.VariableItem     | —        |                                                                            |
| `variables.*.type`                     | body | any                   | —        |                                                                            |
| `variables.*.value`                    | body | any                   | —        |                                                                            |

## Response

| Status    | Body                   | Meaning           |
| --------- | ---------------------- | ----------------- |
| `200`     | o11y.O11yQueryRangeOut | ok                |
| `202`     | Approval               | held for approval |
| `default` | problem-details        | refused           |

`200` body — 2 fields.

| Field    | In   | Type   | Always | Description                                                                                                              |
| -------- | ---- | ------ | ------ | ------------------------------------------------------------------------------------------------------------------------ |
| `data`   | body | any    | —      | Data is the query result — the result type, the result set, execution stats and any warning — as the engine rendered it. |
| `status` | body | string | —      | Status is "success".                                                                                                     |

Failure carries the platform error shape — see [Errors](https://docs.hanzo.ai/docs/errors).

## Examples

**CLI**

```bash
hanzo o11y query_range create
```

**SDK**

**.ts**

```ts
import { Configuration, O11yApi } from 'hanzoai';

const api = new O11yApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.postO11yQueryRange({ compositeQuery: {"queries":[{"spec":"<spec>","type":"<type>"}]}, end: 0 });
```

**.py**

```python
from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import O11yApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = O11yApi(client).post_o11y_query_range(composite_query={"queries":[{"spec":"<spec>","type":"<type>"}]}, end=0)
```

**.go**

```go
cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.O11yAPI.PostO11yQueryRange(context.Background()).Execute()
if err != nil {
	return err
}
```

**.rs**

```rust
use hanzo_client::apis::{configuration::Configuration, o11y_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = o11y_api::post_o11y_query_range(&cfg, Default::default()).await?;
```

**.java**

```java
import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.O11yApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new O11yApi(client).postO11yQueryRange();
```

**HTTP**

```bash
curl -X POST https://api.hanzo.ai/v1/o11y/query_range \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "compositeQuery": {
         "queries": [
           {
             "spec": "<spec>",
             "type": "<type>"
           }
         ]
       },
       "end": 0
     }'
```

**MCP**

MCP reaches **o11y** through the `o11y` tool, which names its 307 operations with its own verbs — this one among them, under a name only MCP declares. `describe` explains any of them:

```bash
curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "describe",
         "arguments": {
           "op": "list_o11y_autocomplete_aggregate_attributes"
         }
       }
     }'
```

---

[O11y API](https://docs.hanzo.ai/docs/openapi/o11y) · [All Hanzo APIs](https://docs.hanzo.ai/docs/openapi) · [Interactive reference](https://docs.hanzo.ai/docs/openapi/reference)