# List export requests

The export API allows you to list all export requests and get their status.

This information is an array of all requests we currently know of for your application. The output contains requests created in the last 3 months. Each object in the array contains exactly the same information as you would get if you made a [GET request](view) with the request id.

### API Description

## List

> List export requests created.

OpenAPI:

```json
{"openapi":"3.1.0","info":{"title":"Batch - REST API","version":"2.6"},"tags":[{"name":"Exports"}],"servers":[{"url":"https://api.batch.com/{version}","description":"production","variables":{"version":{"default":"2.6","description":"Version of the API"}}}],"security":[{"rest_key":[]}],"components":{"securitySchemes":{"rest_key":{"type":"http","scheme":"bearer","description":"## API Key Authentication\n\nAuthentication is required in order to interact with Batch's APIs.\n\nBatch implements authentication using API Keys, that we call the \"REST API Key\".\nYou can find it on your dashboard.\n\nPlease make sure that you keep this key secret. You should never use it in client apps to call APIs from there as it would\neasily be extractable.\n\n### How to authenticate\n\nIn order to authenticate your requests, add your REST API Key in the `Authorization` header and prefix it by `Bearer`. Example: `Authorization: Bearer bcd38d9rfb38ra28`.\n"}}},"paths":{"/exports/list":{"get":{"operationId":"export_list","summary":"List","description":"List export requests created.","tags":["Exports"],"parameters":[{"in":"header","name":"X-Batch-Project","description":"The unique project key, identifying a project on the Batch platform","schema":{"type":"string"},"required":true},{"name":"from","in":"query","description":"A cursor for pagination across multiple pages of results. Don’t include this parameter on the first call. Use the `next_from` value returned in a previous response to request subsequent results.","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"To change the page size of results.","required":false,"schema":{"type":"integer","default":10,"minimum":1,"maximum":100}}],"responses":{"200":{"description":"If the GET to the API endpoint is successful you will receive an HTTP 200 confirmation and information about your export requests. This information is an array of all requests we currently know of for your project. The output contains requests created in the last 4 months.","content":{"application/json":{"schema":{"type":"object","properties":{"exports":{"description":"An array of objects describing each export requests.","type":"array","items":{"type":"object","anyOf":[{"type":"object","required":["id","requested_at","scope","status","files","request"],"properties":{"id":{"type":"string","description":"Id of an export request."},"request_date":{"type":"string","description":"UTC date in a RFC 3339 format."},"completion_date":{"type":"string","description":"UTC date in a RFC 3339 format."},"start_date":{"type":"string","description":"UTC date in a RFC 3339 format."},"scope":{"description":"The scope of the export.","type":"string","enum":["PROFILE_ATTRIBUTES","PROFILE_EVENTS"]},"status":{"description":"The status of the export request.","type":"string","enum":["CREATED","PENDING","RUNNING","ERROR","SUCCESS"]},"files":{"type":"array","description":"All the extraction files available for download if any.","items":{"type":"object","title":"file","properties":{"id":{"type":"string","description":"Id of the extraction file available for download if any."},"part":{"type":"integer","description":"The part number of the file","minimum":1},"size":{"type":"integer","description":"Size of the file in bytes."},"url":{"type":"string","description":"URL to download the file."}}}},"request":{"type":"object","description":"The export request definition.","oneOf":[{"type":"object","title":"Profile Attributes export","required":["export_type"],"properties":{"export_type":{"type":"string","description":"Type of the export events request.","enum":["ATTRIBUTES"]},"attributes":{"type":"array","minItems":1,"items":{"type":"string"},"description":"List of custom or native attributes to be included in the export file(s). Any value that does not start with a `$` will be interpreted as a custom attribute. A list of native attributes available is provided below:\n\n- `$creation_date`\n- `$email_address`\n- `$email_marketing`\n- `$language`\n- `$last_activity`\n- `$last_email_marketing_click`\n- `$last_email_marketing_open`\n- `$last_email_transactional_click`\n- `$last_email_transactional_open`\n- `$last_visit_date`\n- `$phone_number`\n- `$region`\n- `$sms_marketing`\n- `$timezone`\n- `$push_subscriptions`\n- `$install_date`\n"},"identifiers":{"type":"array","minItems":1,"items":{"type":"string","enum":["custom_id","installation_ids"]},"description":"List of profile identifiers to be included in the export file(s)."},"filter":{"type":"object","description":"Optional filter to refine the export. A rate limit applies when using this parameter.","properties":{"segment":{"type":"string","description":"Code of the segment you want to filter this export with."}}}}},{"type":"object","title":"Profile Events export","required":["export_type","from","to","events"],"properties":{"export_type":{"type":"string","description":"Type of the export events request.","enum":["EVENTS"]},"from":{"type":"string","description":"UTC date in a RFC 3339. Must be before `to` parameter and not older than the lookback period."},"to":{"type":"string","description":"UTC date in a RFC 3339 format or `now`."},"identifiers":{"type":"array","items":{"type":"string","enum":["custom_id"]},"description":"List of profile identifiers to be included in the export file(s)."},"events":{"type":"array","minItems":1,"items":{"type":"string","enum":["email_bounced","email_click","email_delivered","email_open","email_sent","email_spam_complaint","email_unsubscribed","sms_sent","sms_bounced","sms_delivered","sms_unsubscribed","push_sent","push_bounced","push_open"]},"description":"List of events to be included in the export file(s)."},"orchestration_ids":{"type":"array","minItems":1,"items":{"type":"string"},"description":"List of orchestrations IDs to be exported. If not provided, all orchestrations will be exported."}}}]}}}]}},"count":{"description":"The number of objects.","type":"integer","minimum":0,"maximum":100},"has_more":{"description":"Whether or not there are more elements available after this set. If `false`, this set comprises the end of the list.","type":"boolean"},"next_from":{"description":"A cursor for use in pagination. If has_more is `true`, you can pass the value of `next_from` to a subsequent call to fetch the next page of results.","type":"string"}}}}}},"400":{"description":"The request is malformed","content":{"application/json":{"schema":{"type":"object","required":["error_message","error_code"],"properties":{"error_message":{"description":"A human readable error message","type":"string"},"error_code":{"description":"Error code","type":"string"}}}}}},"401":{"description":"The Rest API Key is not valid for this project","content":{"application/json":{"schema":{"type":"object","required":["error_message","error_code"],"properties":{"$ref":"#/paths/~1exports~1list/get/responses/400/content/application~1json/schema/properties"}}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"type":"object","required":["error_message","error_code"],"properties":{"$ref":"#/paths/~1exports~1list/get/responses/400/content/application~1json/schema/properties"}}}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"type":"object","required":["error_message","error_code"],"properties":{"$ref":"#/paths/~1exports~1list/get/responses/400/content/application~1json/schema/properties"}}}}},"503":{"description":"Batch's services are under maintenance. Please try again later","content":{"application/json":{"schema":{"type":"object","required":["error_message","error_code"],"properties":{"$ref":"#/paths/~1exports~1list/get/responses/400/content/application~1json/schema/properties"}}}}}}}}}}
```

### Request structure

#### Route

The Export API exposes a GET endpoint that allows you to list all export requests and get their status :

`/exports/list`

#### Headers and authentication

See [Overview → Using Project APIs](../..#request-headers-and-authentication).

### Responses

#### Success

If the GET to the API endpoint is successful you will receive an **HTTP 200** confirmation and information about your export requests.

```json
{
  "exports": [
    {
      "id": "export_nvctr8tgdjf7bppacxxt2aeemnjehfmw",
      "request_date": "2024-02-28T16:28:42Z",
      "scope": "PROFILE_ATTRIBUTES",
      "status": "SUCCESS",
      "request": {
        "export_type": "ATTRIBUTES",
        "attributes": [
          "$region",
          "$phone_number",
          "$timezone",
          "$email_marketing",
          "$sms_marketing",
          "$language",
          "$email_address"
        ],
        "identifiers": [
          "installation_ids",
          "custom_id"
        ]
      },
      "completion_date": "2024-02-28T16:28:48Z",
      "start_date": "2024-02-28T16:28:48Z",
      "files": [
        {
          "id": "file_etxhwckcfc05egew7y97bdjtc75p7g8b",
          "part": 1,
          "size": 592752,
          "url": "https://api.batch.com/2.4/exports/download?id=file_etxhwckcfc05egew7y97bdjtc75p7g8b"
        }
      ]
    }
  ],
  "count": 10,
  "has_more": true,
  "next_from": "ZXhwb3J0X2dnNnN5d2RzcGg2eG00Nm1lZHNtMDRyZ3gyd2FiMDA1QDIwMjQtMDItMjdUMTQ6MTg6NTBa"
}
```

Some information are only available when the `status` field is `SUCCESS`.

If your export request returns no data, the `files` array will be empty.

Pagination infos:

* `next_from` can be used for the next call to list to retrieve the next page
* `count` is the number of items in the current page

#### Failure

If the GET data does not meet the API requirements you will receive an actionable error message. Contact us at [support@batch.com](mailto:support@batch.com) if you need further support.

See the list of potential failures in the API Description.
