Skip to content

Run Profiling and Tests

Trigger a profiling or test run through the API and retrieve its results — for CI/CD pipelines, orchestration tools, or any system that needs to drive TestGen in response to upstream events.

The pattern is the same for every job type: submit, then poll for completion. Profiling and test runs also have a result summary to fetch. Job submissions return immediately — they do not block until the job finishes.

Job lifecycle

A job's status is one of the following. A successful run moves from pending to claimed, running, and completed. The other statuses apply only when a run waits its turn, fails, is canceled, or stops partway.

Status Meaning
pending Submitted, waiting to be picked up
queued Waiting for another run to finish (DuckDB or file data sources only)
claimed Picked up by the system, about to start
running Currently executing
completed Finished successfully
error Failed — see error_message in the job response
cancel_requested Cancellation requested but not yet processed
canceled Cancellation completed
interrupt_requested Stop requested but not yet processed (profiling runs only)
interrupted Stopped partway, keeping its progress; continues on the next scheduler start (profiling runs only)
pause_requested Pause requested but not yet processed (profiling runs only)
paused Stopped partway; continues when resumed (profiling runs only)
resume_requested Set to continue, waiting to be picked up (profiling runs only)

completed, error, and canceled are terminal — once a job reaches one of these, its status does not change. Every other status means the job is still in progress.

A profiling run can stop partway through and keep its progress, then continue from where it stopped. TestGen shutting down mid-run leaves it interrupted, and the next start picks it up on its own; a pause leaves it paused, which continues only when a resume is requested. Test runs do not stop either way.

A job on a DuckDB connection or file data source is queued while it waits for other such jobs to finish, and queued jobs start in the order they were submitted. To change how many of these jobs run at once, see Size TestGen for DuckDB and File Data Sources.

Submit a job

Each job type has its own submission endpoint. Each returns 202 Accepted with the job ID.

Job Endpoint
Profile a table group POST /api/v1/table-groups/{table_group_id}/profiling-runs
Generate tests for a test suite POST /api/v1/test-suites/{test_suite_id}/test-generation
Run a test suite POST /api/v1/test-suites/{test_suite_id}/test-runs

To find a table_group_id, list a project's table groups with GET /api/v1/projects/{project_code}/table-groups, filtering by schema or name to pinpoint the one you want. If the dataset is not set up yet, see Onboard a Dataset.

The response contains the job ID:

{
  "id": "8a4f1c7e-2b39-4e2e-a8c3-1d5e9f2a7b4c",
  "created_at": "2026-05-04T14:22:18Z"
}

Save the id — you use it for polling and for retrieving the result.

A test run also accepts optional settings in the request body. See Test run options.

Poll for completion

GET /api/v1/jobs/{job_id}

Poll until status is one of the three terminal values — completed, error, or canceled. Treat any other status, including interrupted and paused, as still in progress rather than a stopping point, and do not treat an unrecognized status as terminal. Give the poll a timeout: a paused run stays in progress until somebody resumes it from the TestGen UI, which the API does not expose, so it can remain there indefinitely. The response includes the lifecycle timestamps so you can track the job's progress.

{
  "id": "8a4f1c7e-2b39-4e2e-a8c3-1d5e9f2a7b4c",
  "job_key": "run-tests",
  "status": "running",
  "source": "api",
  "created_at": "2026-05-04T14:22:18Z",
  "claimed_at": "2026-05-04T14:22:25Z",
  "started_at": "2026-05-04T14:22:26Z",
  "completed_at": null,
  "error_message": null
}

If the job ends in error, error_message describes what went wrong.

started_at is when the run began and does not move again. claimed_at is when the run was most recently picked up, so a profiling run that stopped partway and continued reports the claim that continued it — later than started_at, and useful for telling how long the current stretch has been going. Measure the whole run from started_at, not from claimed_at.

Fetch the result summary

Once the job status is completed, retrieve the run summary using the job ID.

Job Endpoint
Profile a table group GET /api/v1/profiling-runs/{job_id}
Run a test suite GET /api/v1/test-runs/{job_id}

A test run summary includes the result counts by status and data quality score.

{
  "id": "8a4f1c7e-2b39-4e2e-a8c3-1d5e9f2a7b4c",
  "status": "completed",
  "test_suite_id": "...",
  "table_group_id": "...",
  "started_at": "2026-05-04T14:22:26Z",
  "completed_at": "2026-05-04T14:23:41Z",
  "result": {
    "score": 0.974,
    "result_counts": {
      "passed": 412, "failed": 8, "warning": 3,
      "error": 0, "log": 0, "dismissed": 1
    }
  }
}

A profiling run summary includes the asset counts, the breakdown of hygiene issues and potential PII findings, and the data quality score. The hygiene_issues and potential_pii counts cover active findings only; dismissed findings are totaled separately under dismissed.

{
  "id": "...",
  "status": "completed",
  "table_group_id": "...",
  "started_at": "...",
  "completed_at": "...",
  "result": {
    "score": 0.962,
    "table_ct": 24,
    "column_ct": 318,
    "record_ct": 1842091,
    "issue_counts": {
      "hygiene_issues": { "definite": 4, "likely": 11, "possible": 27 },
      "potential_pii": { "high": 2, "moderate": 5 },
      "dismissed": 0
    }
  }
}

A completed profiling run means profiling itself finished. When the table group is configured to auto-generate tests or monitors, that generation runs as its own follow-up job after profiling — so a completed profiling run does not mean the generated tests are ready yet.

Cancel a job

POST /api/v1/jobs/{job_id}/cancel

Cancellation is asynchronous. The job status moves to cancel_requested first, then to canceled once the system processes the request.

Test run options

A test run submission takes an optional JSON body. Omit it to run the suite as configured.

Field Purpose
match_schema_name Schema to read the second table of each referential test from, for this run only
external_url Link back to the system that started the run
metadata JSON object with any other details about the run 
POST /api/v1/test-suites/{test_suite_id}/test-runs

{
  "match_schema_name": "reference_2026_09_16",
  "external_url": "https://automation.example.com/runs/8891",
  "metadata": {
    "system": "DataOps Automation",
    "run_id": "8891"
  }
}

match_schema_name does not change the stored test definitions. To read the table group's own tables from a different schema, change the table group's schema.

The Test Results page shows external_url and metadata under Link and Run details, and GET /api/v1/test-runs/{job_id} returns them.