Comment on page
Executing workflows via API

Private Beta
This feature is available in Private Beta. Please get in touch with our team to enable it in your account.
A workflow can be executed via an API call, which allows merging workflows with bigger processes, running analytics pipelines from external applications and further integrations that enable a wide range of use cases. 
Enabling API access for a workflow
To enable API access for an existing workflow, click on the three dots in the upper-right corner and find 'API'. Click on 'Enable API access' and you will see a dialog screen that looks like this:
This is an example of an API call that would trigger the execution of a workflow:
curl --location 'https://gcp-us-east1.api.carto.com/v3/sql/your_connection/job' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer eyJhbGc(...)GUH-Lw' \
    --data '{
        "query": "CALL `carto-dw-ac-jfjjof5m.workflows_temp_ernesto_pmadmin_aa2de528.workflow_procedure_09cc2e19ad5bbc6f`(@number_of_clusters,@buffer_radius,@store_type)",
        "queryParameters": {"number_of_clusters":2,"buffer_radius":500,"store_type":"Supermarket"}
    }'
There are a few things that are worth taking into consideration:
It is actually a POST request to CARTO's SQL Batch API, which is used to create jobs to run queries asynchronously. 
The query is a CALL statement for a stored procedure. Workflows will generate a stored procedure in your workflows_temp schema/dataset. The generated SQL is the same that you will obtain by using the 'Export' functionality.
The queryParameters object in the payload contains values for some variables that are passed as inputs to the stored procedure. These variables are the ones marked as 'Parameter' in the 'Variables' menu.
Running a workflow via API call
The provided example uses curl to illustrate the POST request that triggers the execution of the workflow. This example call should be easily adapted to other methods in different languages, like the requests library in Python.
The response to that call will look like the following:
{
  "externalId": "job_h8UWzpdzX0s2XAAXQd3rdWCdPUT9",
  "accountId": "ac_jfakef5m",
  "userId": "auth0|61164b7xxx77c006a259f53",
  "connectionId": "5a32a0ea-555a-48dd-aeb1-8768aae8ef1c",
  "metadata": {},
  "createdAt": "2023-10-04T16:10:35.732Z",
  "query": "CALL `carto-dw-ac-jfjjof5m.workflows_temp_ernesto_pmadmin_aa2de528.workflow_procedure_09cc2e19ad5bbc6f`(@number_of_clusters,@buffer_radius,@store_type)",
  "jobMetadata": {
    "location": "US"
  },
  "token": "eyJhbGc(...)GUH-Lw"
}
You can use that externalId to make a request to check the status of the execution, like:
curl --location 'https://gcp-us-east1.api.carto.com/v3/sql/your_connection/job/job_h8UWzpdzX0s2XAAXQd3rdWCdPUT9' \
--header 'Authorization: Bearer eyJhbGc(...)GUH-Lw' 
The above is just an example that is using a specific API URL (gcp-us-east1.api.carto.com) and connection name. Please make sure that you use the same API endpoint that you obtained from the UI and you used to create the job in the first place.
The response to that is a JSON that contains metadata about the query execution, including a status object with information about the execution status.
The following is an example of a failed execution due to incorrect parameter types:
    "status": {
      "errorResult": {
        "reason": "invalidQuery",
        "location": "query",
        "message": "Query error: Cannot coerce expression @number_of_clusters to type INT64 at [1:158]"
      },
      "state": "DONE"
    }
While this would be an example of a successful execution:
    "status": {
      "state": "DONE"
    }
Get more information about using the job endpoint in the CARTO API documentation.
Updating your workflow
Whenever you want to propagate changes in your workflow to the corresponding stored procedure that is executed with an API call, you need to update it.
For that, just click on the chip in the top header that says 'API enabled', which will open the API endpoint modal. Wait for a couple of seconds while CARTO checks for changes in the workflow and you will see this:
Click on 'Update' to sync the workflow that is executed via API with the current state of the workflow in the UI.
Disabling API access
If you need to prevent API access for a workflow, just click on 'Disable API access' in the API endpoint modal and confirm:
Using variables in workflows
Temporary data in Workflows
Last modified 2mo ago