> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Scheduling artifacts via the API

export const maia = "Maia";

By scheduling artifacts, you can automate pipeline executions based on pre-defined conditions. You can either:

* Specify an artifact version to use.
* Always select the latest version.

***

## Creating a schedule

Base URL: `POST /v1/projects/{projectId}/schedules`

You need to obtain the `projectId` using the following GET call: `/v1/projects`.

Read [{maia} Public API](/docs/api-reference/maia-api-overview) for comprehensive reference material about each endpoint.

***

## Default artifact selection

* If no `versionName` is provided, the schedule will always use the latest deployed or promoted artifact in the specified environment.
* The latest artifact is determined based on the most recent deployment or promotion, not by version name.

<img src="https://mintcdn.com/matillion/ZzkpJtArzaSJvx8j/images/api-reference/scheduling-artifacts/scheduling-artifacts-01.png?fit=max&auto=format&n=ZzkpJtArzaSJvx8j&q=85&s=8088011c018a04b1f095e0a4d57c48fa" alt="Schedules" width="1216" height="400" data-path="images/api-reference/scheduling-artifacts/scheduling-artifacts-01.png" />

***

## Fixed artifact version

If a specific `versionName` is provided, the schedule will always trigger pipelines within that specific artifact version.

***

## Variable overrides

* Variable overrides allow you to dynamically adjust execution parameters when creating a schedule. This means that instead of relying solely on default or preset values within the artifact, you can define specific values at runtime, ensuring flexibility in different environments or scenarios.
* When creating a schedule, you can pass variable overrides as part of the request body. These overrides will temporarily replace the values defined within the artifact for that particular execution.

### Example request - schedule with variable overrides

```sh theme={null}
curl --location --request POST 'https://abc.xyz.matillion.com/dpc/v1/projects/91697e59-87ad-4345-bc11-59352b432e5d/schedules' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "versionName": "About-version 2.0",
    "environmentName": "test-environment",
    "scalarVariables": {
        "var1": "customValue1",
        "var2": "customValue2"
    }
}'
```

***

## Create a schedule with a version name

### Request

```sh theme={null}
curl --location --request POST 'https://abc.xyz.matillion.com/dpc/v1/projects/91697e59-87ad-4345-bc11-59352b432e5d/schedules?versionName=About-version 2.0&environmentName=testenvironment' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJrdmRxeThOd0thZ05qYnZoUHljVkVCOXE4V0dTRTNEZmpfWDdla0hmYXEwIn...
```

### Response

```sh theme={null}
{
    "scheduleId": "ef097ecf-c130-4d9b-bfc5-ca888c8ad482"
}
```

***

## Get schedule details using a schedule id

### Request

```sh theme={null}
curl --location --request GET 'https://abc.xyz.matillion.com/dpc/v1/projects/91697e59-87ad-4345-bc11-59352b432e5d/schedules/ef097ecf-c130-4d9b-bfc5-ca888c000000' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJrdmRxeThOd0thZ05qYnZoUHljVkVCOXE4V0dTRTNEZmpfWDdla0hmYXEwIn00...
```

### Response

```sh theme={null}
{
    "pipelineName": "child job.orch.yaml",
    "scalarVariables": {
    "var1": "value1"
},
```

***

## Preventing concurrent schedule executions

You can use the setting `allowConcurrentExecutions` enable concurrent executions. Manual use of this setting is optional and defaults to `true` if a value is not manually supplied.

* If `allowConcurrentExecutions = true`: the schedule runs as normal, even if a previous execution is still running.
* If `allowConcurrentExecutions = false`:
  * If a previous execution is still running when the schedule is triggered again, the new execution is prevented.
  * Once the previous execution finishes, the next scheduled run will proceed as normal.

Example request with `allowConcurrentExecutions`:

```json theme={null}
{
    "versionName": "About-version 2.0",
    "environmentName": "test-environment",
    "allowConcurrentExecutions": false
}
```