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.

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

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
}

Template Test Execution

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

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:

Job and Template Test Results

The status field returns one of:

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
• Informatica
• Apache Airflow
• Generic REST (Other Orchestrators)