---
title: "Orchestration Integrations"
slug: "orchestration-integrations"
updated: 2026-09-22T16:10:37Z
published: 2026-09-22T16:10:37Z
canonical: "docs.validatar.com/orchestration-integrations"
---

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

# Orchestration Integrations

## Overview

Validatar's Execution API enables orchestration tools to trigger test and job execution, poll for completion, and take action based on results. This allows you to embed data quality gates directly into your ETL/ELT pipelines — if quality checks fail, the pipeline can stop before propagating bad data downstream.

## Authentication

All orchestration API calls use a custom header for authentication:

```
x-val-api-token: {your_api_token}
```

Create an API token in Validatar under **Settings > Authentication > API Tokens** with the **Execution** scope enabled. A single token can have multiple scopes if you also need Authoring or Explorer access. For full details on token creation, see [User Tokens](https://docs.validatar.com/docs/user-tokens).

## Base URL

All endpoints use the pattern:

```
{VALIDATAR_API_URL}/core/api/v1/{endpoint}
```

Replace `{VALIDATAR_API_URL}` with your Validatar instance URL (e.g., `https://mycompany.cloud.validatar.com`).

## Common Pattern

All orchestration integrations follow the same core workflow:

1. **Trigger** — POST to the execute endpoint for a job (or individual test)
2. **Poll** — GET the results endpoint every 5 seconds until execution completes
3. **Evaluate** — parse the result status to determine pass/fail
4. **Act** — continue the pipeline, halt, or raise an alert based on the evaluation

> **Tip:** For standard test execution, the API supports a `waitUntilComplete` option that makes the call synchronous — the response only returns after the test finishes. This can simplify integrations that don't need polling. Jobs and template tests always require polling.

## Key API Endpoints

| Endpoint | Method | Description |
| --- | --- | --- |
| `projects/{projectId}/jobs/{jobId}/execute` | POST | Execute a job |
| `projects/{projectId}/jobs/{jobId}/results/{batchKey}` | GET | Get job execution summary |
| `projects/{projectId}/tests/{testId}/execute` | POST | Execute a standard test |
| `projects/{projectId}/tests/{testId}/results/{batchKey}` | GET | Get standard test summary |
| `projects/{projectId}/template-tests/{testId}/execute` | POST | Execute a template test |
| `projects/{projectId}/template-tests/{testId}/results/{batchKey}` | GET | Get template test summary |

> **Note:** Jobs are the recommended execution unit for orchestration. A job groups multiple tests into a single execution with a defined order, so you can trigger one API call and get a consolidated result.

## Finding IDs

The project, test, and job IDs you need are visible in the Validatar UI URL. For example:

```
https://mycompany.cloud.validatar.com/projects/43/folders/1408/tests/57878
                                               ^^                   ^^^^^
                                          project ID              test ID
```

You can also retrieve IDs programmatically using the Authoring API:

- `GET /core/api/v1/projects` — returns all projects with their IDs
- `GET /core/api/v1/projects/{projectId}/jobs/{jobId}` — returns job details

## Execute Request Bodies

### Job Execution

Job execution requires no request body — just the project ID and job ID in the URL:

```
POST /core/api/v1/projects/{projectId}/jobs/{jobId}/execute
```

### Standard Test Execution

```
{
  "saveInRepository": true,
  "waitUntilComplete": false,
  "leftDataSourceId": null,
  "rightDataSourceId": null
}
```

| Field | Type | Description |
| --- | --- | --- |
| `saveInRepository` | bool | Set to `true` to persist results (recommended) |
| `waitUntilComplete` | bool | Set to `true` for synchronous execution (no polling needed) |
| `leftDataSourceId` | int? | Override the test's source data source (optional) |
| `rightDataSourceId` | int? | Override the test's target data source (optional) |

### Template Test Execution

```
{
  "saveInRepository": true,
  "parallelTestCount": 10,
  "childTestId": null
}
```

| Field | Type | Description |
| --- | --- | --- |
| `saveInRepository` | bool | Set to `true` to persist results (recommended) |
| `parallelTestCount` | int | Number of child tests to run in parallel (default: 10) |
| `childTestId` | int? | Execute only a specific child test (optional) |

## Execute Response

All execute endpoints return the same response shape:

```
{
  "name": "My Job Name",
  "executionKey": "abc123-def456",
  "batchId": 12345
}
```

Use the `executionKey` value as the `batchKey` parameter when polling for results.

## Result Evaluation

### Standard Test Results

The `result` field returns one of:

| Value | Meaning | Pipeline Action |
| --- | --- | --- |
| `Running` | Execution still in progress | Continue polling |
| `Passed` | Test passed | Continue pipeline |
| `Failed` | Test failed | Fail or alert |
| `Error` | Execution error | Fail or alert |

### Job and Template Test Results

The `status` field returns one of:

| Value | Meaning | Pipeline Action |
| --- | --- | --- |
| `Running` | Execution still in progress | Continue polling |
| `Completed` | All steps finished | Evaluate individual test results |
| `Aborted` | Execution was cancelled | Fail or alert |
| `Aborting` | Cancellation in progress | Continue polling |
| `Abandoned` | Execution failed to start | Fail or alert |

For jobs, the response also includes a `tests` array with individual test outcomes. Check each test's `status` to determine the overall quality gate result.

## Polling Best Practices

- **Poll every 5 seconds** — this balances responsiveness with load on the Validatar server
- **Implement a timeout** — set a configurable maximum wait time (default: 30 minutes) to avoid hanging pipelines
- **Log each poll response** — include the status and elapsed time for troubleshooting
- **Handle network errors gracefully** — a failed poll request doesn't mean the test failed; retry the poll

## Guides in This Section

- [Azure Data Factory](/docs/azure-data-factory)
- [Informatica](/docs/informatica)
- [Apache Airflow](/docs/apache-airflow)
- [Generic REST (Other Orchestrators)](/docs/generic-rest-orchestration)
- [Python-Driven Test Generation](/docs/python-driven-test-generation)