> For the complete documentation index, see [llms.txt](https://docs.searchagora.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.searchagora.com/catalog/data-connector.md).

# Data connector

POST `/data-connector-export`

This endpoint lets you export data from any store on Agora in a data structure that you specify. To export many stores at once, use [Mass export](https://docs.searchagora.com/catalog/data-connector#mass-export) below.

**Headers**

| Header          | Type   | Description   |
| --------------- | ------ | ------------- |
| `Authorization` | string | Bearer token. |

**Request body**

| Parameter     | Type   | Description                                                                                                        |
| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------ |
| `export_type` | string | Required. File format: json or csv.                                                                                |
| `storeId`     | string | Required. The store to export.                                                                                     |
| `fields`      | array  | Required. At least one `{ key, value }` object. `key` is the Agora field, `value` is the column name in your file. |

```json
{
  "export_type": "json", // allowed values are json and csv
  "storeId": "66ecc57244e70f26ceb60629",
  "fields": [
    {
      "key": "name",
      "value": "Product Name"
    },
    {
      "key": "brand",
      "value": "Brand"
    }
  ]
}
```

**Fields**

Every row includes `id`, the Agora product ID, as the first column at no cost. You only need to send `id` in `fields` if you want to rename it. Only active products are exported.

| Key                 | Type   | Credits per row |
| ------------------- | ------ | --------------- |
| `id`                | string | Free            |
| `name`              | string | 1               |
| `brand`             | string | 1               |
| `storeName`         | string | 1               |
| `slug`              | string | 1               |
| `description`       | string | 1               |
| `category`          | string | 1               |
| `subcategory`       | string | 1               |
| `categories`        | array  | 1               |
| `externalProductId` | string | Free            |
| `price`             | number | 3               |
| `url`               | string | 3               |
| `images`            | array  | 3               |
| `averageRating`     | number | 3               |
| `variants`          | array  | 3               |
| `agoraScore`        | number | 5               |

**Pricing**

* Each row costs the rate of the highest-priced field that has a value on that row.
* Fields that are empty on a product are not charged for that product.
* Every export has a 100 credit minimum. A mass export counts as one export.
* Exports over 1,000,000 rows need a Scale or Enterprise plan.
* Credits are charged only after the file is ready. Failed exports are not charged.

Use [Quote an export](https://docs.searchagora.com/catalog/data-connector#quote-an-export) to see the exact cost first. See [Pricing](https://docs.searchagora.com/introduction/pricing) for how credits work.

**Response headers**

| Header                | Description                      |
| --------------------- | -------------------------------- |
| `Content-Disposition` | File name of the export.         |
| `X-Credits-Charged`   | Credits charged for this export. |
| `X-Credits-Remaining` | Your balance after the charge.   |

**Response**

{% tabs %}
{% tab title="200 (JSON)" %}

```json
{
  "data": [
    {
      "id": "6994c8a459391dc6d29de7ff",
      "Product Name": "Women's Runner NZ Slip On - Dark Navy (Dark Navy Sole)",
      "Brand": "Allbirds"
    },
    {
      "id": "6994c8a459391dc6d29de806",
      "Product Name": "Men's Runner NZ Slip On - Light Grey (Light Grey Sole)",
      "Brand": "Allbirds"
    },
    {
      "id": "6994c8a459391dc6d29de817",
      "Product Name": "Men's Allbirds Slide - Natural Black",
      "Brand": "Allbirds"
    }
  ],
  "total": 30
}
```

{% endtab %}

{% tab title="200 (CSV)" %}

```csv
id,Product Name,Brand
6994c8a459391dc6d29de7ff,Women's Runner NZ Slip On - Dark Navy (Dark Navy Sole),Allbirds
6994c8a459391dc6d29de806,Men's Runner NZ Slip On - Light Grey (Light Grey Sole),Allbirds
6994c8a459391dc6d29de817,Men's Allbirds Slide - Natural Black,Allbirds
```

{% endtab %}

{% tab title="404" %}

```json
{
  "status": false,
  "message": "Store not found"
}
```

{% endtab %}
{% endtabs %}

### Quote an export

POST `/data-connector-export/quote`

This endpoint lets you see how many credits a single-store export will cost before you run it. It's free.

**Headers**

| Header          | Type   | Description   |
| --------------- | ------ | ------------- |
| `Authorization` | string | Bearer token. |

**Request body**

| Parameter | Type   | Description                                                  |
| --------- | ------ | ------------------------------------------------------------ |
| `storeId` | string | Required. The store to price.                                |
| `fields`  | array  | Required. Same keys as the export. `value` is optional here. |

```json
{
  "storeId": "66ecc57244e70f26ceb60629",
  "fields": [
    { "key": "name" },
    { "key": "brand" }
  ]
}
```

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "status": true,
  "data": {
    "rows": 30,
    "rowsAt5": 0,
    "rowsAt3": 0,
    "rowsAt1": 30,
    "rowsAt0": 0,
    "breakdown": [
      { "creditsPerRow": 1, "rows": 30 }
    ],
    "tier": "catalog",
    "creditsPerRow": 1,
    "rawCredits": 30,
    "totalCredits": 100,
    "minimumApplied": true,
    "minCredits": 100,
    "billableFields": ["name", "brand"],
    "emptyFields": [],
    "maxRowsSelfServe": 1000000,
    "exceedsLargeExportLimit": false,
    "largeExportAllowed": true
  }
}
```

{% endtab %}

{% tab title="404" %}

```json
{
  "status": false,
  "message": "Store not found"
}
```

{% endtab %}
{% endtabs %}

### Mass export

Mass export lets you export many stores in one job. The job runs in the background and builds a ZIP with one file per store, then emails you a download link. Credits are charged once, when the ZIP is ready, for the rows actually included. Fields and pricing are the same as the single-store export.

1. Quote the export with `POST /data-connector-mass-export/quote`.
2. Start it with `POST /data-connector-mass-export`.
3. Check progress with `GET /data-connector-mass-export/{jobId}`, or wait for the email.

### Quote a mass export

POST `/data-connector-mass-export/quote`

This endpoint lets you see how many credits a multi-store export will cost before you run it. It's free.

**Headers**

| Header          | Type   | Description   |
| --------------- | ------ | ------------- |
| `Authorization` | string | Bearer token. |

**Request body**

| Parameter  | Type  | Description                                                               |
| ---------- | ----- | ------------------------------------------------------------------------- |
| `storeIds` | array | Store IDs. Send `storeIds`, `stores` or both.                             |
| `stores`   | array | Store names.                                                              |
| `fields`   | array | Required. Same keys as the single-store export. `value` is optional here. |

You can send up to 10,000 stores per request. Duplicates are removed. One quote covers the whole selection, with one 100 credit minimum and one 1,000,000 row limit.

```json
{
  "stores": ["Allbirds", "Gymshark"],
  "fields": [
    { "key": "name" },
    { "key": "price" },
    { "key": "agoraScore" }
  ]
}
```

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "status": true,
  "data": {
    "rows": 35890,
    "rowsAt5": 12000,
    "rowsAt3": 20000,
    "rowsAt1": 3890,
    "rowsAt0": 0,
    "breakdown": [
      { "creditsPerRow": 5, "rows": 12000 },
      { "creditsPerRow": 3, "rows": 20000 },
      { "creditsPerRow": 1, "rows": 3890 }
    ],
    "tier": "agora_score",
    "creditsPerRow": 5,
    "rawCredits": 123890,
    "totalCredits": 123890,
    "minimumApplied": false,
    "minCredits": 100,
    "billableFields": ["name", "price", "agoraScore"],
    "emptyFields": [],
    "totalStores": 2,
    "requestedStores": 2,
    "storesNotFound": [],
    "totalFields": 3,
    "maxRowsSelfServe": 1000000,
    "exceedsLargeExportLimit": false,
    "largeExportAllowed": true
  }
}
```

{% endtab %}

{% tab title="401" %}

```json
{
  "status": "error",
  "message": "API key is required"
}
```

{% endtab %}
{% endtabs %}

### Start a mass export

POST `/data-connector-mass-export`

This endpoint lets you start a multi-store export. It returns right away with a `jobId` while the ZIP is built in the background.

**Headers**

| Header          | Type   | Description   |
| --------------- | ------ | ------------- |
| `Authorization` | string | Bearer token. |

**Request body**

| Parameter     | Type   | Description                                                                    |
| ------------- | ------ | ------------------------------------------------------------------------------ |
| `export_type` | string | File format of each store file in the ZIP: json or csv. The default is json.   |
| `email`       | string | Where the download link is sent. The default is your account email.            |
| `storeIds`    | array  | Store IDs. Send `storeIds`, `stores` or both, up to 10,000 stores.             |
| `stores`      | array  | Store names.                                                                   |
| `fields`      | array  | Required. `{ key, value }` objects. `value` is required and can't contain `:`. |

```json
{
  "export_type": "csv",
  "email": "you@company.com",
  "stores": ["Allbirds", "Gymshark"],
  "fields": [
    {
      "key": "name",
      "value": "Product Name"
    },
    {
      "key": "price",
      "value": "Price"
    },
    {
      "key": "externalProductId",
      "value": "SKU"
    }
  ]
}
```

**Good to know**

* You can run one mass export at a time.
* Your plan and balance are checked before the job starts. Credits are charged after the ZIP is uploaded.
* Stores with no active products are skipped and listed under `skipped`.
* The emailed link works for 7 days.

**Response**

{% tabs %}
{% tab title="202" %}

```json
{
  "status": true,
  "message": "Your export is being processed. We will email the download link to you@company.com as soon as it is ready.",
  "data": {
    "jobId": "671a0f2c9b1e4a0012abcdef",
    "status": "processing",
    "email": "you@company.com",
    "exportType": "csv",
    "fields": ["name:Product Name", "price:Price", "externalProductId:SKU"],
    "totalFields": 3,
    "totalStores": 2,
    "processedStores": 0,
    "exportedStores": 0,
    "totalProducts": 0,
    "skipped": [],
    "fileName": "agora-catalog-export-2026-11-13-abcdef.zip",
    "fileSize": 0,
    "downloadUrl": null,
    "estimatedCredits": 123890,
    "creditsCharged": 0,
    "error": null,
    "errorCode": null,
    "createdAt": "2026-11-13T10:00:00.000Z",
    "startedAt": "2026-11-13T10:00:00.000Z",
    "finishedAt": null,
    "expiresAt": null
  }
}
```

{% endtab %}

{% tab title="409" %}

```json
{
  "status": false,
  "code": "MASS_EXPORT_IN_PROGRESS",
  "message": "You already have a mass export running. We will email you when it is ready.",
  "jobId": "671a0f2c9b1e4a0012abcdef"
}
```

{% endtab %}
{% endtabs %}

### Mass export status

GET `/data-connector-mass-export/{jobId}`

This endpoint lets you check the progress of a mass export. It's free.

**Headers**

| Header          | Type   | Description   |
| --------------- | ------ | ------------- |
| `Authorization` | string | Bearer token. |

**Path parameters**

| Parameter | Type   | Description                                       |
| --------- | ------ | ------------------------------------------------- |
| `jobId`   | string | The `jobId` returned when you started the export. |

Check every few seconds while `status` is `processing`. When it's `completed`, `downloadUrl` holds a link that works for about an hour. Request the status again to get a fresh link.

| Status       | Description                                              |
| ------------ | -------------------------------------------------------- |
| `processing` | The ZIP is being built.                                  |
| `completed`  | Ready. `downloadUrl` is set and the email has been sent. |
| `expired`    | More than 7 days since it finished. Start a new export.  |
| `failed`     | See `error` and `errorCode`. Not charged.                |
| `stalled`    | The job stopped mid-run. Start a new export.             |

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "status": true,
  "data": {
    "jobId": "671a0f2c9b1e4a0012abcdef",
    "status": "completed",
    "email": "you@company.com",
    "exportType": "csv",
    "fields": ["name:Product Name", "price:Price", "externalProductId:SKU"],
    "totalFields": 3,
    "totalStores": 2,
    "processedStores": 2,
    "exportedStores": 2,
    "totalProducts": 35890,
    "skipped": [],
    "fileName": "agora-catalog-export-2026-11-13-abcdef.zip",
    "fileSize": 12582912,
    "downloadUrl": "https://...",
    "estimatedCredits": 123890,
    "creditsCharged": 123890,
    "error": null,
    "errorCode": null,
    "createdAt": "2026-11-13T10:00:00.000Z",
    "startedAt": "2026-11-13T10:00:00.000Z",
    "finishedAt": "2026-11-13T10:12:00.000Z",
    "expiresAt": "2026-11-20T10:12:00.000Z"
  }
}
```

{% endtab %}

{% tab title="404" %}

```json
{
  "status": false,
  "code": "MASS_EXPORT_NOT_FOUND",
  "message": "Mass export not found"
}
```

{% endtab %}
{% endtabs %}

### Mass export errors

| Status | Code                          | Description                                                                       |
| ------ | ----------------------------- | --------------------------------------------------------------------------------- |
| 400    | `MASS_EXPORT_NO_STORES`       | No `stores` or `storeIds` were sent when starting an export.                      |
| 400    | `MASS_EXPORT_TOO_MANY_STORES` | More than 10,000 stores.                                                          |
| 400    | `MASS_EXPORT_NO_EMAIL`        | No email in the request or on the account.                                        |
| 400    | `MASS_EXPORT_NO_PRODUCTS`     | None of the stores have active products.                                          |
| 402    | `OUT_OF_CREDITS`              | Not enough credits. The response includes `requiredCredits` and `currentCredits`. |
| 403    | `CATALOG_EXPORT_PLAN_LIMIT`   | Over 1,000,000 rows without a Scale or Enterprise plan.                           |
| 404    | `MASS_EXPORT_NOT_FOUND`       | Unknown `jobId`.                                                                  |
| 409    | `MASS_EXPORT_IN_PROGRESS`     | You already have a mass export running. The response includes its `jobId`.        |
| 429    | `MASS_EXPORT_BUSY`            | The server is busy. Try again later.                                              |
