# 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 %}