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
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)

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 stops when TestGen is shut down partway through it and continues on the next start, so a run submitted through the API can pass through interrupted before reaching completed. Test runs do not stop this way.

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}

Poll until status is one of the three terminal values — completed, error, or canceled. Treat any other status, including interrupted, as still in progress rather than a stopping point, and do not treat an unrecognized status as terminal. 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.