# List orchestrations

## List

> List orchestrations.

```json
{"openapi":"3.1.0","info":{"title":"Batch - REST API","version":"2.9"},"tags":[],"servers":[{"url":"https://api.batch.com/{version}","description":"production","variables":{"version":{"default":"2.10","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"}},"parameters":{"HeaderProjectKey":{"in":"header","name":"X-Batch-Project","description":"The unique project key, identifying a project on the Batch platform","schema":{"type":"string"},"required":true}},"schemas":{"Campaign":{"type":"object","description":"Details for a campaign orchestration.","properties":{"id":{"type":"string","description":"Unique identifier for the orchestration."},"type":{"type":"string","enum":["campaign"]},"channels":{"type":"array","items":{"type":"string","enum":["push","sms","email"]},"description":"Channels used by the orchestration."},"platforms":{"type":"array","items":{"type":"string","enum":["ios","android","web"]},"description":"Platforms targeted by the orchestration."},"source":{"type":"string","description":"Source of the orchestration creation."},"created_date":{"type":"string","format":"date-time","description":"Date and time when the orchestration was created."},"name":{"type":"string","description":"Name of the orchestration."},"labels":{"type":"array","items":{"type":"string"},"description":"Labels associated with the orchestration."},"status":{"type":"string","description":"Current status of the orchestration.","enum":["draft","running","completed","stopped"]},"start_time":{"type":"string","format":"date-time","description":"Date and time when the orchestration started."},"has_mobile_landing":{"type":"boolean","description":"Whether a mobile landing is attached to the push."}}},"Recurring":{"title":"Recurring & Warmup","type":"object","description":"Details for a recurring orchestration.","properties":{"id":{"type":"string","description":"Unique identifier for the orchestration."},"type":{"type":"string","enum":["recurring"]},"channels":{"type":"array","items":{"type":"string","enum":["push","sms","email"]},"description":"Channels used by the orchestration."},"platforms":{"type":"array","items":{"type":"string","enum":["ios","android","web"]},"description":"Platforms targeted by the orchestration."},"source":{"type":"string","description":"Source of the orchestration creation."},"created_date":{"type":"string","format":"date-time","description":"Date and time when the orchestration was created."},"name":{"type":"string","description":"Name of the orchestration."},"labels":{"type":"array","items":{"type":"string"},"description":"Labels associated with the orchestration."},"status":{"type":"string","description":"Current status of the orchestration.","enum":["draft","running","completed","stopped"]},"start_time":{"type":"string","format":"date-time","description":"Date and time when the orchestration started."},"recurrence":{"type":"object","properties":{"end_time":{"type":"string","format":"date-time","description":"End date and time for the recurrence."},"repeat_unit":{"type":"string","enum":["WEEKLY","DAILY","MONTHLY","YEARLY"],"description":"Unit for recurrence frequency."},"repeat_frequency":{"type":"integer","description":"How often the recurrence unit repeats."}}},"capping":{"type":"integer","description":"Maximum number of times the recurring orchestration can run."},"has_mobile_landing":{"type":"boolean","description":"Whether a mobile landing is attached to the push."}}},"TriggerAutomation":{"type":"object","title":"Trigger Automation","description":"Details for a trigger orchestration.","properties":{"id":{"type":"string","description":"Unique identifier for the orchestration."},"type":{"type":"string","enum":["trigger"]},"channels":{"type":"array","items":{"type":"string","enum":["push","sms","email"]},"description":"Channels used by the orchestration."},"platforms":{"type":"array","items":{"type":"string","enum":["ios","android","web"]},"description":"Platforms targeted by the orchestration."},"source":{"type":"string","description":"Source of the orchestration creation."},"created_date":{"type":"string","format":"date-time","description":"Date and time when the orchestration was created."},"name":{"type":"string","description":"Name of the orchestration."},"labels":{"type":"array","items":{"type":"string"},"description":"Labels associated with the orchestration."},"status":{"type":"string","description":"Current status of the orchestration.","enum":["draft","running","completed","stopped"]},"start_time":{"type":"string","format":"date-time","description":"Date and time when the orchestration started."},"capping":{"type":"integer","description":"Maximum number of times the trigger orchestration can run."},"end_time":{"type":"string","format":"date-time","description":"End date and time for the trigger orchestration."},"nbr_steps":{"type":"integer","description":"Total number of steps in the trigger orchestration."},"nbr_message_steps":{"type":"integer","description":"Number of message steps in the trigger orchestration."},"has_mobile_landing":{"type":"boolean","description":"Whether a mobile landing is attached to the push."},"message_steps":{"type":"array","items":{"type":"object","properties":{"step_name":{"type":"string","description":"The name of the step."},"step_id":{"type":"string","description":"The API identifier of the step."}}}}}},"InApp":{"type":"object","title":"In-App","description":"Details for an in-app orchestration.","properties":{"id":{"type":"string","description":"Unique identifier for the orchestration."},"type":{"type":"string","enum":["trigger"]},"channels":{"type":"array","description":"Channels used by the orchestration.","items":{"type":"string","enum":["in_app"]}},"platforms":{"type":"array","description":"Platforms targeted by the orchestration.","items":{"type":"string","enum":["ios","android"]}},"source":{"type":"string","description":"Source of the orchestration creation."},"created_date":{"type":"string","format":"date-time","description":"Date and time when the orchestration was created."},"name":{"type":"string","description":"Name of the orchestration.","exeample":"Test Campaign 1"},"labels":{"type":"array","items":{"type":"string"},"description":"Labels associated with the orchestration."},"status":{"type":"string","description":"Current status of the orchestration.","enum":["draft","running","completed","stopped"]},"start_time":{"type":"string","format":"date-time","description":"Start date and time for the in-app orchestration."},"end_time":{"type":"string","format":"date-time","description":"End date and time for the in-app orchestration."},"capping":{"type":"integer","description":"Maximum number of times the trigger orchestration can run."}}},"Error":{"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"}}}},"responses":{"400":{"description":"The request is malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The Rest API Key is not valid for this project","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Batch's services are under maintenance. Please try again later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/orchestrations/list":{"get":{"operationId":"orchestrations_list","summary":"List","description":"List orchestrations.","tags":["Orchestrations"],"parameters":[{"$ref":"#/components/parameters/HeaderProjectKey"},{"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.","schema":{"type":"string"}},{"name":"limit","in":"query","description":"A limit on the number of objects to be returned.","schema":{"type":"integer","maximum":100,"default":10}},{"name":"status","in":"query","description":"Filter orchestrations by status.","schema":{"type":"array","items":{"type":"string","enum":["draft","running","completed","stopped"]},"default":["running","completed"]},"style":"form","explode":true},{"name":"type","in":"query","description":"Filter orchestrations by type. If not provided, all types are returned.","schema":{"type":"array","items":{"type":"string","enum":["campaign","recurring","trigger","warmup"]},"default":["campaign","recurring","trigger","warmup"]},"style":"form","explode":true,"required":false},{"name":"channels","in":"query","description":"Filter orchestrations by channels. If not provided, all channels are returned.","schema":{"type":"array","items":{"type":"string","enum":["email","push","in-app","sms","universal"]},"default":["email","push","in-app","sms","universal"]},"style":"form","explode":true}],"responses":{"200":{"description":"Successful response with a list of orchestrations.","content":{"application/json":{"schema":{"type":"object","properties":{"orchestrations":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/Campaign"},{"$ref":"#/components/schemas/Recurring"},{"$ref":"#/components/schemas/TriggerAutomation"},{"$ref":"#/components/schemas/InApp"}]}},"count":{"description":"The total number of objects.","type":"integer"},"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":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"429":{"$ref":"#/components/responses/429"},"500":{"$ref":"#/components/responses/500"},"503":{"$ref":"#/components/responses/503"}}}}}}
```

### Request structure

#### Route

The orchestration API exposes a GET endpoint that allows you to export a list of Orchestrations with key information like name, creation date, and channel.

`/orchestrations/list`

#### Headers and authentication

See [Overview → Using Project APIs](https://doc.batch.com/developer/api/cep/..#request-headers-and-authentication).

#### Query parameters

See the API Description.

### Responses

#### Success

A successful `GET` request to this endpoint will return an `HTTP 200 OK` response. The body of the response will contain a JSON array of orchestration objects that match the provided query parameters.

Each orchestrations in the array includes the following fields :

* id (string) : A unique identifier for the orchestration. This identifier can also be used to query for the orchestration's statistics.
* type (string) : The type of orchestration. Possible values are `campaign`, `recurring`, or `trigger`.
* Core details : source, name, status, created\_date, start\_time, channels
* The following additional fields may also be present if applicable:
  * `labels` (array): An array of labels associated with the orchestration. This is available for all orchestration types.
  * `recurrence` (object): A block of data describing the recurrence rules. This field is only present for `recurring` orchestrations.
  * `messages_steps` (array): An array of objects, where each object represents a step in the message flow and includes its `step_name` and `step_id`. This field is only present for `trigger`orchestrations.

Note: The content of the messages is not included in the response.

```json
{
  "orchestrations": [
   {
      "id": "orchestration_06bw2hjbja6dzui3r71r1vff7s1xbq63",
      "type": "onetime",
      "channels": [
        "email"
      ],
      "source": "dashboard",
      "name": "my_campaign_1",
      "status": "completed",
      "created_date": "2025-06-30T14:38:19Z",
      "labels": [
        "NEWSLETTER"
      ],
      "start_time": "2025-06-30T17:31:00Z"
    },
    {
      "id": "orchestration_068a348ws8zjtfwfxvjzpe9sv4tsqcc1k",
      "type": "recurring",
      "channels": [
        "sms"
      ],
      "source": "dashboard",
      "capping": 0,
      "recurrence": {
        "repeat_unit": "weekly",
        "repeat_fequency": 1
      },
      "name": "welcome_campaign",
      "status": "running",
      "created_date": "2025-03-30T12:00:25Z",
      "start_time": "2025-04-01T12:54:00Z"
    }
  ],
  "count": 18,
  "has_more": true,
  "next_from": "U29sZGVzX0N1aXNzYXJkc19Db3JlX0ZlbW1lX0NsaWVudHNAMjAyNS0wNi0zMFQxMjo1MzozNlo="
}
```

If your request returns no data, the `orchestrations` 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> if you need further support.

See the list of potential failures in the API Description.