# Export

**Exports** are a special kind of [search](https://docs.commercelayer.io/metrics/getting-started/queries/search) query where the result data are converted into a tabular format (**CSV**). When performing an export query on the Metrics API endpoint, you get in the [response](#response) a CSV file (text/csv) returned inline, containing the requested `fields` (sorted and filtered) of the actual records that match the query.

{% hint style="warning" %}
The maximum size allowed for the results of an export query is **100K** records. Export queries matching a higher number of records will return a `422 UNPROCESSABLE ENTITY` error.
{% endhint %}

### Request

To perform an export query, send a `POST` request to the `/{{resource_name}}/export` 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>  "search": {
</strong>    "sort": "...",
    "sort_by": "...",
    "fields": [ ... ]
  },
  "filter": { ... }
}
</code></pre>

#### Query keys

<table><thead><tr><th>Key</th><th width="149.3984375">Type</th><th width="120.00390625" data-type="checkbox">Required</th><th width="179.58203125">Description</th><th width="299.2421875">Values</th></tr></thead><tbody><tr><td><strong><code>sort</code></strong></td><td>String</td><td>false</td><td>The way you want the results of the query to be sorted.</td><td>One of <code>asc</code> or <code>desc</code> (default is <code>desc</code>).</td></tr><tr><td><strong><code>sort_by</code></strong></td><td>String</td><td>false</td><td>The date field you want the results of the query sorted by.</td><td>The available values for this key depend on the resource you're searching (see <a href="https://app.gitbook.com/s/lhTYC557IzGiJNS84RKD/resources/orders/export#sort_by-values">orders</a>, <a href="https://app.gitbook.com/s/lhTYC557IzGiJNS84RKD/resources/returns/export#sort_by-values">returns</a>, or <a href="https://app.gitbook.com/s/lhTYC557IzGiJNS84RKD/resources/carts/export#sort_by-values">carts</a> for the related lists). Default is <code>{{resource_name}}.current_date</code> (i.e. the datetime of the resource's latest status change).</td></tr><tr><td><strong><code>fields</code></strong></td><td>Array</td><td>false</td><td>The list of fields you want to be exported for each record.</td><td>The available values for this key depend on the resource you're searching (see <a href="https://app.gitbook.com/s/lhTYC557IzGiJNS84RKD/resources/orders/export#field-values">orders</a>, <a href="https://app.gitbook.com/s/lhTYC557IzGiJNS84RKD/resources/returns/export#field-values">returns</a>, or <a href="https://app.gitbook.com/s/lhTYC557IzGiJNS84RKD/resources/carts/export#field-values">carts</a> for the related lists). If empty, <a href="#allowed-and-default-fields">default fields</a> will be exported.</td></tr></tbody></table>

#### Allowed and default fields

Unlike in the [search](https://docs.commercelayer.io/metrics/getting-started/queries/search) query:

* Only the root resource (i.e. order or return) and single-level references are allowed (e.g. no line items or return line items).
* The `fields` array can be empty. If so, some default fields will be exported (see [example](#default-export)). The list of default fields depends on the resource you're exporting (see [orders](https://app.gitbook.com/s/lhTYC557IzGiJNS84RKD/resources/orders/export#field-values), [returns](https://app.gitbook.com/s/lhTYC557IzGiJNS84RKD/resources/returns/export#field-values), or [carts](https://app.gitbook.com/s/lhTYC557IzGiJNS84RKD/resources/carts/export#field-values) for more information).
* No [meta](https://docs.commercelayer.io/metrics/api-specification#meta) information is returned.
* No [pagination](https://docs.commercelayer.io/metrics/getting-started/search#pagination) is available for the results (all the records will be exported up to the maximum limit allowed).

### Response

The response of an export query is a plain **CSV** file (text/csv) returned inline and containing a maximum of **100K** records, sorted by the date field specified in the `sort_by` key. For each record, all the fields requested in the `fields` array (if specified) are exported.

{% hint style="info" %}
In case of multiple tags for the same resource, `tags.name` and `tags.id` will generate space-separated values within the related table column (see [example](#exporting-specific-fields)).
{% endhint %}

### Examples

{% hint style="info" %}
The following examples will focus on the [query](https://docs.commercelayer.io/metrics/api-specification#query) part of the request. No specific [filter](https://docs.commercelayer.io/metrics/api-specification#filter) will be defined (i.e. all the results will be filtered by the [default filter](https://docs.commercelayer.io/metrics/filters#default-filter)). See the [use cases](https://docs.commercelayer.io/metrics/getting-started/use-cases) section for more complex combinations of queries and filters.
{% endhint %}

#### Default export

{% tabs %}
{% tab title="Request" %}
The following request performs an export query with an empty body to export as CSV the default fields of the matching orders, sorted by the default date field (i.e. the order's latest status change):

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

{% endtab %}

{% tab title="Response" %}
On success, the API responds with a `200 OK` status code, returning inline the default data in a plain CSV (text/csv) format:

<pre class="language-csv"><code class="lang-csv"><strong>order.id,order.placed_at,order.total_amount_with_taxes
</strong>PvoJhvvgBl,2026-03-09T18:25:18.773Z,105.0
wjobhXXZeQ,2026-03-09T18:25:17.098Z,109.0
qLmohgdeEo,2026-03-09T18:25:11.318Z,99.0
qeWdhKKXOgQ,2026-03-09T18:25:06.620Z,25.0
...,...,...
</code></pre>

{% endtab %}
{% endtabs %}

#### Exporting specific fields

{% tabs %}
{% tab title="Request" %}
The following request performs an export query to get information about the orders ID, last time of update, the associated customer ID and email, and the orders tags name (if any), sorted in ascending order by the time when they were updated:

<pre class="language-sh"><code class="lang-sh">curl -g -X POST \
  'https://{{your_domain}}.commercelayer.co/metrics/orders/export' \
  -H 'Accept: application/vnd.api.v1+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Authorization: Bearer {{your_access_token}}' \
  -d '{
<strong>    "search": {
</strong>      "sort": "asc",
      "sort_by": "order.updated_at",
<strong>      "fields": [
</strong>        "order.id",
        "order.updated_at",
        "customer.id",
        "customer.email",
        "tags.name"
      ]
    }
  }'
</code></pre>

{% endtab %}

{% tab title="Response" %}
On success, the API responds with a `200 OK` status code, returning inline the requested data in a plain CSV (text/csv) format:

<pre class="language-csv"><code class="lang-csv"><strong>order.id,order.updated_at,customer.id,customer.email,tags.name
</strong>NFerhmmmkG,2026-02-09T06:02:36.306Z,OGYbvdjZAk,rodolfo@example.org,
qRKshdddsM,2026-02-09T13:10:27.349Z,QjmyhKsomO,tristin@hotmail.com,
qeWdhKKKL,2026-02-09T13:10:29.125Z,kqzXcBlDLn,godfrey@gmail.com,
<strong>wJCVhoooaO,2026-02-09T13:10:29.297Z,QRfhbKRVQ,candice@hotmail.com,vip fraud
</strong><strong>wXErhmmmYG,2026-02-09T13:10:31.442Z,QRFgvvlLXk,jerry@gmail.com,vip
</strong>wdyBhFFFjm,2026-02-09T13:10:31.797Z,QaAxhkiWJQ,emmalee@hotmail.com,
<strong>wOBnhCCCnG,2026-02-09T13:10:35.928Z,kpZXhXvqBO,lester@yahoo.com,first-order free-gift vip
</strong>PEBrhBBvKj,2026-02-09T13:10:37.607Z,nMzjcxbDaO,alan@yahoo.com,
wjobhJCXM,2026-02-09T13:10:39.537Z,QKmohjporn,lucindayahoo.com,
qkykhrrddQ,2026-02-09T13:10:41.126Z,OJXhJWdPO,gina@mail.com,
...,...,...,...,...
</code></pre>

{% 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/export.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.