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 both job types: submit, poll for completion, then fetch the result summary. Job submissions return immediately — they do not block until the job finishes.

Job lifecycle

Every job moves through this set of statuses:

Status Meaning
pending Submitted, waiting to be picked up
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

completed, error, and canceled are terminal. Once a job reaches one of these, its status does not change.

Submit a job

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

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

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.

Poll for completion

GET /api/v1/jobs/{job_id}

Call this endpoint until status is completed, error, or canceled. The response includes the lifecycle timestamps so you can track the job's progress through claim, start, and completion.

{
  "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.

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,
    "tests": {
      "passed": 412, "failed": 8, "warning": 3,
      "error": 0, "log": 0, "dismissed": 1
    }
  }
}

A profiling run summary includes the asset counts, hygiene-issue breakdown, and data quality score.

{
  "id": "...",
  "status": "completed",
  "table_group_id": "...",
  "started_at": "...",
  "completed_at": "...",
  "result": {
    "score": 0.962,
    "table_ct": 24,
    "column_ct": 318,
    "record_ct": 1842091,
    "issues": { "definite": 4, "likely": 11, "possible": 27, "dismissed": 0 }
  }
}

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.