POST /workflow/runs¶
Use the POST /workflow/runs endpoint to start a workflow.
Available HTTP methods¶

Prerequisites¶
Base URL¶
All requests made to the POST /workflow/runs endpoint should be directed to the following base URL:
https://{tenant-id}.amperity.com/api/workflow/runs
Rate limit¶
A rate limit is the number of requests that may be made to the Amperity API in a given time period.
The Amperity API supports requests to endpoints that do not exceed a rate of 10 requests per second. Response times will vary by endpoint and the complexity of data that is returned by the response. Some requests may take seconds to return.
Requests to the Amperity API that exceed 10 requests per second may return an error response with an HTTP 429 status code.
Requests¶
A request to the POST /workflow/runs endpoint is similar to:
curl --request POST \
'https://app.amperity.com/api/workflow/runs' \
--header 'amperity-tenant: tenant' \
--header 'api-version: 2024-04-01' \
--header 'Authorization: Bearer token' \
--data '{"config_id"="cg-123ABc4DE"}'
(This example is formatted for readability in a narrow page layout.)
Request parameters¶
The following table describes the parameters that may be used with the POST /workflow/runs endpoint.
Parameter |
Description |
---|---|
api_version |
String. Optional. A supported version of the Amperity API. For example: 2024-04-01. Note You may use the api-version request header instead of the api_version request parameter. |
config_id |
String. Required. The configuration ID of the workflow. This may be the ID for a courier group, orchestration group, or campaign. You can find the ID for the workflow to be run in the following locations:
|
range_from |
String. Required for file-based workflows. Courier groups only. Important A value for range_from must be specified for any courier group that is configured to pull files from cloud storage (SFTP, Amazon S3, Azure Blob Storage, or Google Cloud Storage). A timestamp that defines the start (inclusive) of the time window for which couriers in the workflow should pull data. See the range_to request parameter. A timestamp must be in ISO 8601 format and in Coordinated Universal Time (UTC). Tip Use with range_to to define a date range within which to look for files. This date range will be inclusive of range_from and exclusive of range_to. Use without range_to to define a specific day on which to run the workflow. |
range_to |
String. Optional. Courier groups only. Important A value for range_from must be specified when range_to is included in the request. A timestamp that defines the end (exclusive) of the time window for which couriers in the workflow should pull data. See the range_from request parameter. A timestamp must be in ISO 8601 format and in Coordinated Universal Time (UTC). |
run_mode |
String. Optional. Courier groups only. Indicates the run mode for the courier group workflow. Possible values: full, refresh, or source.
Tip run_mode will default to the run mode that is configured for the scheduled workflow. You may override the configured setting by providing a value for run_mode in the request. |
Request examples¶
The following examples show how to send requests to the POST /workflow/runs endpoint.
cURL, run campaign¶
The following example shows how to use cURL to send a request to the POST /workflow/runs endpoint to run a campaign.
curl --request POST \
'https://app.amperity.com/api/workflow/runs' \
--header 'amperity-tenant: tenant' \
--header 'api-version: 2024-04-01' \
--header 'Authorization: Bearer token' \
--data '{"config_id"="cc-123ABc4DE"}'
(This example is formatted for readability in a narrow page layout.)
cURL, run courier group¶
The following example shows how to use cURL to send a request to the POST /workflow/runs endpoint to run a courier group.
curl --request POST \
'https://app.amperity.com/api/workflow/runs' \
--header 'amperity-tenant: tenant' \
--header 'api-version: 2024-04-01' \
--header 'Authorization: Bearer token' \
--data '{"config_id"="cg-123ABc4DE"}' \
--data '{"range_from"="YYYY-MM-DD"}' \
--data '{"range_to"="YYYY-MM-DD"}' \
--data '{"run_mode"="full"}'
(This example is formatted for readability in a narrow page layout.)
cURL, run orchestration¶
The following example shows how to use cURL to send a request to the POST /workflow/runs endpoint to run an orchestration.
curl --request POST \
'https://app.amperity.com/api/workflow/runs' \
--header 'amperity-tenant: tenant' \
--header 'api-version: 2024-04-01' \
--header 'Authorization: Bearer token' \
--data '{"config_id"="og-123ABc4DE"}'
(This example is formatted for readability in a narrow page layout.)
Python¶
The following example shows how to use Python to send a request to the POST /workflow/runs endpoint.
import requests
# Your API endpoint
url = "https://app.amperity.com/api/workflow/runs"
bearer_token = dbutils.secrets.get(scope = "tenant-bridge-api-access", key = "tenant-bridge-api-access")
# Headers including authorization and custom headers
headers = {
"Authorization": f"Bearer {bearer_token}",
"amperity-tenant": "bridge",
"api-version": "2024-04-01"
}
# Body of the request
body = {
"config_id": "cg-2efo5X8vo",
"range_from": "YYYY-MM-DD",
"range_to": "YYYY-MM-DD",
"run_mode": "source"
}
# Make the POST request
response = requests.post(url, headers=headers, json=body)
# Print the response
print("Status Code:", response.status_code)
print("Response Body:", response.text)
Responses¶
A response from the POST /workflow/runs endpoint will match an HTTP status code. A 200 response will contain workflow details for the workflow run that was started. A 4xx response indicates an issue with the configuration of your request. A 5xx response indicates that the endpoint is unavailable.
200 OK¶
The 200 response returns details for the workflow that was started, similar to:
{
"task_instances":[],
"id":"wf-123456A-78901-2bcd3e",
"name":"Daily",
"principal_name":"Daniel Kuhlman",
"principal_id":"abc-EFghIjKL1Mn",
"type":"courier.group/run",
"launched_version":"abc-123456A-78901-2bcd3",
"state":"scheduled",
"created_at":"2025-04-18T15:33:51.724Z",
"tenant":"bridge",
"current_version":"abc-123456A-78901-2bcd3"
}
Response parameters¶
A 200 OK response contains the following parameters.
Parameter |
Description |
---|---|
created_at |
The date and time at which the workflow started. |
current_version |
A unique identifier that describes the configuration state of Amperity at the start of the workflow. The value for this property is similar to: “etv-20240210-12345-6AbCDE”. |
id |
The Amperity internal identifier for the workflow. For example wf-20240619-14418-6UhqSe. |
launched_version |
A unique identifier that describes the configuration state of Amperity at the start of the workflow. The value for this property is similar to: “etv-20240210-12345-6AbCDE”. |
name |
The name of the workflow. Note This is the same value that is visible from the title of each individual workflow page and from the Name column on the Workflows page. |
principal_id |
A unique identifier for the Amperity user who started the workflow. For example: “google-apps|socktown@socktown.com”. |
principal_name |
The name of the Amperity user who started the workflow. For example: “Daniel Kuhlman” or “Automated workflow”. |
state |
The state of the workflow. |
task_instances |
A JSON array that contains zero (or more) sets of the following parameters, one set for each task in the workflow. The list of parameters returned in the response may vary, depending on the type of task.
Note This is the same value that is visible from the Task column on each individual workflow page.
|
tenant |
The unique identifier for the tenant. |
type |
The type of workflow. Most workflows will have workflow types related to the following areas within Amperity:
Note This is the same value that is visible from the Type box on each individual workflow page and from the Type column on the Workflows page. |