# Stats

**Stats** are numeric computations (based on specific [operators](https://docs.commercelayer.io/metrics/getting-started/queries/..#query-operators)) calculated over values extracted from a specific field of the selected resource. When performing a stats query on the Metrics API endpoint you get in the [response](#response) the value of the computation (based on the selected `operator`) on the selected `field`.

### Request

To perform a date breakdown query send a `POST` request to the `/{{resource_name}}/stats` endpoint specifying the [query keys](#query-keys) and [filter](https://docs.commercelayer.io/metrics/getting-started/filters) parameters:

<pre class="language-json"><code class="lang-json">{
<strong>  "stats": {
</strong>    "field": "...",
    "operator": "..."
  },
  "filter": { ... },
  "meta": { ... }
}
</code></pre>

#### Query keys

<table><thead><tr><th>Key</th><th>Type</th><th data-type="checkbox">Required</th><th>Description</th><th>Values</th></tr></thead><tbody><tr><td><strong><code>field</code></strong></td><td>String</td><td>true</td><td>The field you want the metrics or statistics computed on.</td><td>The available values for this key depend on the resource you're doing statistics on (see <a href="https://app.gitbook.com/s/lhTYC557IzGiJNS84RKD/resources/orders/stats#operators-and-field-values">orders</a>, <a href="https://app.gitbook.com/s/lhTYC557IzGiJNS84RKD/resources/returns/stats#operators-and-field-values">returns</a>, or <a href="https://app.gitbook.com/s/lhTYC557IzGiJNS84RKD/resources/carts/stats#operators-and-field-values">carts</a> for the related lists).</td></tr><tr><td><strong><code>operator</code></strong></td><td>String</td><td>false</td><td>The computing operator.</td><td>The available operators depend on the <code>field</code> key value (see <a href="https://app.gitbook.com/s/lhTYC557IzGiJNS84RKD/resources/orders/stats#operators-and-field-values">orders</a>, <a href="https://app.gitbook.com/s/lhTYC557IzGiJNS84RKD/resources/returns/stats#operators-and-field-values">returns</a>, or <a href="https://app.gitbook.com/s/lhTYC557IzGiJNS84RKD/resources/carts/stats#operators-and-field-values">carts</a> for the related lists). Default is <code>sum</code>.</td></tr></tbody></table>

### Response

The response of a stats query returns the value of the computation (based on the operator specified in the `operator` key) on the field specified in the `field` key. The value type depends on the [operator](https://docs.commercelayer.io/metrics/getting-started/queries/..#query-operators) itself — it can be an object made of multiple numeric values (`stats`) or a simple integer/float number (any other operator):

<pre class="language-json"><code class="lang-json">{
  "data": {
<strong>    "value": ...
</strong>  },
  "meta": { ... }
}
</code></pre>

### Example

{% hint style="info" %}
The following example will be focused on the [query](https://docs.commercelayer.io/metrics/api-specification#query) part of the request. So no specific [filter](https://docs.commercelayer.io/metrics/api-specification#filter) or [meta](https://docs.commercelayer.io/metrics/api-specification#meta) options will be defined (i.e. all the results will be filtered by the [default filter](https://docs.commercelayer.io/metrics/filters#default-filter) and the response won't include the request payload). See the [use cases](https://docs.commercelayer.io/metrics/getting-started/use-cases) section for more complex combinations of queries and filters.
{% endhint %}

{% tabs %}
{% tab title="Request" %}
The following request performs a stats query to get the average order total amount:

<pre class="language-sh"><code class="lang-sh">curl -g -X POST \
  'https://{{your_domain}}.commercelayer.io/metrics/orders/stats' \
  -H 'Accept: application/vnd.api.v1+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Authorization: Bearer {{your_access_token}}' \
  -d '{
<strong>    "stats": {
</strong>      "field": "order.total_amount_with_taxes",
      "operator": "avg"
    }
  }'
</code></pre>

{% endtab %}

{% tab title="Response" %}
On success, the API responds with a `200 OK` status code, returning the computed value in the `data` object and additional information in the `meta` object:

```json
{
  "data": {
    "value": 123.45
  },
  "meta": {
    "type": "stats",
    "trace_id": "f9df8a29-b5fe-4b4b-9a4d-f51017abb13b",
    "mode": "test",
    "organization_id": "xYZkjABcde",
    "market_ids": [ "yzXKjYzaCx", "..." ]
  }
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.commercelayer.io/metrics/getting-started/queries/stats.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.