---
title: Endpoints reference - APIs
description: Data Export API endpoints reference
lastUpdated: 09 May 2025
source_url:
  html: https://docs.contentsquare.com/en/api/export/endpoints-reference/
  md: https://docs.contentsquare.com/en/api/export/endpoints-reference/index.md
---

## Create an export job

POST /v1/exports

This endpoint allows for creating a new export job.

### Request parameters

* #### name   string   Required

  The name of the export. Must not be empty.

* #### format   string   Required

  The file format of the export output.

  Possible values: `JSONL`, or `CSV`.

* #### scope   string (<= 255 chars)  

  The scope of the export.

* #### frequency   object   Required

  The frequency of the export.

  * #### value   string  

    The frequency value.

    Possible values: `once`, `daily`, or `hourly`.

  * #### dateRange.from   string  

    Required only if frequency.value is "once". The value must be a valid ISO 8601 date string. It should be anterior to frequency.dateRange.to, but not anterior to the project data retention period

  * #### dateRange.to   string  

    Required only if frequency.value is "once". The value must be a valid ISO 8601 date string. It should be posterior but not more than 7 days after frequency.dateRange.from.

* #### fields   object   Required

  The list of fields to export.\
  To list the exportable fields for a given scope, see the [dedicated endpoint](https://docs.contentsquare.com/en/api/export/endpoints-reference/#get-the-list-of-all-exportable-fields).

  * #### fieldName   string   Required

    A valid `fieldName` corresponding to the name property of the fields that can be listed via the [/v1/exportable-fields](https://docs.contentsquare.com/en/api/export/endpoints-reference/#get-the-list-of-all-exportable-fields) endpoint. You cannot specify a `fieldName` more than once, except for the special values `custom_var` and `dynamic_var` (used to export custom or dynamic variables).

  * #### aliasName   string  

    An alias that will be used to rename the exported field in the output file.

  * #### customVarPosition   string  

    Required only if `custom_var` is specified as `fieldName`. The custom variable position. Must be between 1 and 20 inclusive. To learn more about custom variables, see [Sending custom vars](https://docs.contentsquare.com/en/web/sending-custom-vars/). To list custom variables available on the authenticated project, see the [/v1/custom\_vars](https://docs.contentsquare.com/en/api/export/endpoints-reference/#get-the-list-of-custom-variables) endpoint.

  * #### dynamicVarKey   string  

    Required only if `dynamic_var` is specified as `fieldName`. The dynamic variable key. To learn more about dynamic variables, see [Sending dynamic vars](https://docs.contentsquare.com/en/web/sending-dynamic-vars/). To list dynamic variables available on the authenticated project, see the [/v1/dynamic\_var\_keys](https://docs.contentsquare.com/en/api/export/endpoints-reference/#get-the-list-of-dynamic-variables) endpoint.

* #### deviceLabel   string   Required

  A device filter.

  Possible values: `all`, `desktop`, `mobile`, or `tablet`.

* #### segmentId   string  

  A valid `segmentId`. If no segment is provided, the data for all users will be exported. To retrieve the list of available segments for the project, you can call the [/v1/segment](https://docs.contentsquare.com/en/api/metrics/objects-endpoints/#segments) endpoint.

### Request example 1

```shell
curl --location --request POST 'https://api.contentsquare.com/v1/exports' \
--header 'Authorization: Bearer <your_access_token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Test API POST",
    "format": "JSONL",
    "scope": "sessions",
    "frequency": {
        "value": "daily"
    },
    "fields": [
        {
            "fieldName": "project_id",
        },
        {
            "fieldName": "session_id",
        }
    ],
    "deviceLabel": "all",
    "segmentId": 123
}'
```

### Request example 2

```shell
curl --location --request POST 'https://api.contentsquare.com/v1/exports' \
--header 'Authorization: Bearer <your_access_token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Test API POST",
    "format": "CSV",
    "scope": "views",
    "frequency": {
        "value": "once",
        "dateRange": {
            "from": "2023-02-14T00:00:00.000Z",
            "to": "2023-02-15T23:59:59.999Z"
        }
    },
    "fields": [
        {
            "fieldName": "session_id",
            "aliasName": "Session ID"
        },
        {
            "fieldName": "view_number",
            "aliasName": "View number in session"
        },
        {
            "fieldName": "custom_var",
            "customVarPosition": 2,
            "aliasName": "My Custom Variable of index 2"
        },
        {
            "fieldName": "dynamic_var",
            "dynamicVarKey": "AB Test",
            "aliasName": "Experiment"
        }
    ],
    "deviceLabel": "desktop",
    "segmentId": 123
}'
```

### Response example

```json
{
  "payload": {
    "jobId": 1372
  },
  "success": true
}
```

## Get the list of all export jobs

GET /v1/exports

This endpoint provides the list of all the available export jobs (be they in status active, suspended, computing or completed).

### Query parameters

* #### format   string  

  To filter based on the export format (see [Enumerations](https://docs.contentsquare.com/en/api/export/enumerations/#format))

* #### frequency   string  

  To filter based on the export frequency (see [Enumerations](https://docs.contentsquare.com/en/api/export/enumerations/#format))

* #### limit   integer  

  To change the page size of results (25 by default, 100 max).

* #### order   string  

  To change the order of the results list ("ASC" or "DESC", "DESC" by default). Ordering is based on the `jobId`.

* #### page   integer  

  The page of results to retrieve.

* #### scope   string  

  To filter based on the job scope (see [Enumerations](https://docs.contentsquare.com/en/api/export/enumerations/#scope)).

* #### state   string  

  To filter based on the job status (see [Enumerations](https://docs.contentsquare.com/en/api/export/enumerations/#state-job-state))

### Request example

```shell
curl --location --request GET 'https://api.contentsquare.com/v1/exports?state=completed' \
--header 'Authorization: Bearer <your_access_token>'
```

### Response example

```json
{
  "payload": [
    {
      "jobId": 0,
      "name": "string",
      "ownerId": 0,
      "lastUpdatorId": 0,
      "accountId": 0,
      "nextFrom": "2021-05-02T16:22:43.439Z",
      "nextTo": "2021-05-02T16:22:43.439Z",
      "projectIds": [0],
      "state": "ACTIVE",
      "createdAt": "2021-05-02T16:22:43.439Z",
      "format": "JSON",
      "scope": "views",
      "frequency": "string",
      "fields": [
        {
          "fieldName": "string",
          "aliasName": "string"
        }
      ],
      "lastRunTime": "2021-05-02T16:22:43.439Z",
      "nextRunTime": "2021-05-02T16:22:43.439Z",
      "updatedAt": "2021-05-02T16:22:43.439Z",
      "filters": {
        "deviceId": 0
      }
    }
  ],
  "success": true
}
```

`nextFrom` and `nextTo` represent the next date range that will be extracted, while `lastRunTime` and `nextRunTime` indicate when the last and next execution started / will start.

## Get the list of all successful job runs

GET /v1/exports/successful-runs

This endpoint provides the list of all the jobs runs that completed successfully. Use it to find which jobs have generated extraction files to be downloaded.

### Query parameters

* #### page   integer  

  The page of results to retrieve.

* #### order   string  

  To change the order of the results list ("ASC" or "DESC", "DESC" by default). Ordering is based on the `jobId`.

* #### limit   integer  

  To change the page size of results (25 by default, 100 max).

### Request example

```shell
curl --location --request GET 'https://api.contentsquare.com/v1/exports/successful-runs' \
--header 'Authorization: Bearer <your_access_token>'
```

### Response example

```json
{
  "payload": [
    {
      "jobId": 0,
      "jobRunId": 0,
      "name": "string",
      "projectIds": [0],
      "from": "2021-05-02T16:40:14.022Z",
      "to": "2021-05-02T16:40:14.022Z",
      "completionTime": "2021-05-02T16:40:14.022Z",
      "format": "JSONL",
      "scope": "views",
      "frequency": "string",
      "nbOfFiles": 0
    }
  ],
  "success": true
}
```

## Get a specific job

GET /v1/exports/{jobId}

This endpoint allows for retrieving a specific job with its ID.

### Path parameters

* #### jobId   integer   Required

  The Job ID.

### Request example

```shell
curl --location --request GET 'https://api.contentsquare.com/v1/exports/1234' \
--header 'Authorization: Bearer <your_access_token>'
```

### Response example

```json
{
  "payload": {
    "jobId": 0,
    "name": "string",
    "ownerId": 0,
    "lastUpdatorId": 0,
    "accountId": 0,
    "nextFrom": "2021-05-02T16:50:29.301Z",
    "nextTo": "2021-05-02T16:50:29.301Z",
    "projectIds": [0],
    "state": "ACTIVE",
    "createdAt": "2021-05-02T16:50:29.301Z",
    "format": "JSONL",
    "scope": "views",
    "frequency": "string",
    "fields": [
      {
        "fieldName": "string",
        "aliasName": "string"
      }
    ],
    "lastRunTime": "2021-05-02T16:50:29.301Z",
    "nextRunTime": "2021-05-02T16:50:29.301Z",
    "updatedAt": "2021-05-02T16:50:29.301Z",
    "filters": {
      "deviceId": 0
    }
  },
  "success": true
}
```

`nextFrom` and `nextTo` represent the next date range that will be extracted, while `lastRunTime` and `nextRunTime` indicate when the last and next execution started / will start.

## Get the list of all job runs of a job

GET /v1/exports/{jobId}/runs

This endpoint provides the list of all the job runs related to a specific job.

### Path parameters

* #### jobId   integer   Required

  The Job ID.

### Query parameters

* #### limit   integer  

  To change the page size of results (25 by default, 100 max).

* #### order   string  

  To change the order of the results list ("ASC" or "DESC", "DESC" by default). Ordering is based on the `jobId`.

* #### page   integer  

  The page of results to retrieve.

* #### state   string  

  To filter based on the job status (see [Enumerations](https://docs.contentsquare.com/en/api/export/enumerations/#state-job-state)).

### Request example

```shell
curl --location --request GET 'https://api.contentsquare.com/v1/exports/1354/runs' \
--header 'Authorization: Bearer <your_access_token>'
```

### Response example

```json
{
  "payload": [
    {
      "jobRunId": 0,
      "startDate": "2021-05-02T16:51:51.004Z",
      "state": "CREATED",
      "endDate": "2021-05-02T16:51:51.004Z",
      "completionRate": 0
    }
  ],
  "success": true
}
```

## Get a specific job run

GET /v1/exports/{jobId}/runs/{runId}

This endpoint allows for retrieving a specific job run with its ID. The response includes all the extraction files available for download if any (in the `files` field). The files can be downloaded via the provided URL in the `url` field. Files will not be available for download after the `expirationDate`.

### Path parameters

* #### jobId   integer   Required

  The Job ID.

* #### runId   integer   Required

  The Job Run ID.

### Request example

```shell
curl --location --request GET 'https://api.contentsquare.com/v1/exports/1354/runs/67226' \
--header 'Authorization: Bearer <your_access_token>'
```

### Response example

```json
{
  "payload": {
    "jobRunId": 0,
    "startDate": "2021-05-02T16:54:55.983Z",
    "state": "CREATED",
    "files": [
      {
        "partId": 0,
        "fileSize": 0,
        "url": "string",
        "expirationDate": "2021-05-02T16:54:55.983Z"
      }
    ],
    "endDate": "2021-05-02T16:54:55.983Z",
    "completionRate": 0
  },
  "success": true
}
```

## Get the list of all exportable fields

GET /v1/exportable-fields

This endpoint allows for retrieving all fields that can be extracted for a specified scope (the list of fields will depend on the scope).

### Query parameters

* #### scope   string   Required

  To filter based on the job scope (see [Enumerations](https://docs.contentsquare.com/en/api/export/enumerations/#state-job-state))

### Request example

```shell
curl --location --request GET 'https://api.contentsquare.com/v1/exportable-fields?scope=sessions' \
--header 'Authorization: Bearer <your_access_token>'
```

### Response example

```json
{
  "payload": [
    {
      "name": "string",
      "description": "string",
      "example": "string",
      "aliases": ["string"],
      "parameters": ["string"]
    }
  ],
  "success": true
}
```

## Get the list of custom variables

GET /v1/custom-vars

This endpoint allows for retrieving all the custom variables available on a project. To learn more about custom variables, see [Sending custom vars](https://docs.contentsquare.com/en/web/sending-custom-vars/).

### Parameters

* No parameters.

### Request example

```shell
curl --location --request GET 'https://api.contentsquare.com/v1/custom-vars' \
--header 'Authorization: Bearer <your_access_token>'
```

### Response example

```json
{
    "payload": [
        {
            "position": 2,
            "key": "dataType",
            "values": [
                "journey",
                "recording",
                "zoning"
            ]
        },
        {
            "position": 3,
            "key": "pageType",
            "values": [
                "checkoutstep 1"
                "checkoutstep 2",
                "checkoutstep 3",
            ]
        },
        {
            "position": 1,
            "key": "Goal achieved",
            "values": [
                "false",
                "true"
            ]
        }
    ],
    "success": true
}
```

## Get the list of dynamic variables

GET /v1/dynamic-var-keys

This endpoint allows for retrieving all the dynamic variables available on a project between two dates. To learn more about dynamic variables, see [Sending dynamic variables](https://docs.contentsquare.com/en/web/sending-dynamic-vars/).

### Query parameters

* #### from   ISO 8601 date string  

  Start date of the query date range.

* #### to   ISO 8601 date string  

  End date of the query date range.

### Request example

```shell
curl --location --request GET 'https://api.contentsquare.com/v1/dynamic-var-keys?from=2023-02-10T00:00:00&to=2023-02-17T00:00:00' \
--header 'Authorization: Bearer <your_access_token>'
```

### Response example

```json
{
  "payload": [
    {
      "key": "AB Test",
      "type": "string"
    },
    {
      "key": "Traffic Source",
      "type": "string"
    },
    {
      "key": "VoC feedback score",
      "type": "string"
    },
    {
      "key": "Web Analytics Segment",
      "type": "string"
    }
  ],
  "success": true
}
```