> ## Documentation Index
> Fetch the complete documentation index at: https://docs.go.aiinsurance.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Data Validation Run
> Reports the progress and results of a **data validation run** started by
**`POST /configuration/data-validation-runs`**.
Poll this until `status` is `succeeded` or `failed`. The counts climb as the scan
progresses, so a poll mid-scan is a real partial reading, not a placeholder.
### Statuses
- **`queued`** — the run exists and is waiting for a worker. Its counts are all
`0`. This is a normal state that every run passes through, **not** a stall: the
run is recorded before the background work is dispatched.
- **`running`** — the scan is in progress; the counts climb.
- **`succeeded`** — the whole book was scanned. `finishedAt` is set, `error` is
`null`.
- **`failed`** — the scan stopped early. `finishedAt` is set and `error` carries
the reason. Start a new run to retry.
### The counts
`recordsScanned` is how many records the scan has classified so far. The other
three are **independent, overlapping** buckets — a record with an undeclared key
*and* a value that breaks is counted in both, so **they do not sum to
`recordsScanned`**:
- **`recordsAdhering`** — records that would persist cleanly under the scanned
configuration: no undeclared keys and no violations.
- **`recordsWithExtraKeys`** — records holding keys the scanned configuration no
longer declares. Suspect, not necessarily fatal.
- **`recordsBreaking`** — records holding a value that would **fail** a write
under the scanned configuration (a changed type or cardinality, an option-set
key that no longer exists, a broken relational reference, a violated
invariant).
There is deliberately **no total and no percentage**: producing a denominator
would mean counting every record of every entity type before the scan could
report anything. Treat `recordsScanned` as a monotonic progress signal, and the
terminal `status` as completion.
Per-record detail — *which* records and *which* fields — is not part of this
response.
### How long a run stays readable
A run's status stays readable for as long as the run exists — nothing removes a
run on a timer, and however long ago it completed this endpoint still reports
it. **A run's age is never a failure:** a run that exists is reported in full
however long ago it finished, and no response reports a run as too old to read.
**Required permission:** `company.configuration:export`
This endpoint requires an API key created with the **FMV1_CONFIGURATION_MANAGER** role.
See [Authentication](/api-reference/authentication) for how to create API keys with specific roles.
## OpenAPI
````yaml /openapi/generated-external-api.yaml get /api/v1/companies/{companyId}/configuration/data-validation-runs/{runId}
openapi: 3.0.3
info:
title: AI Insurance External API
description: External API for AI Insurance platform
version: 1.0.0
contact:
email: support@aiinsurance.io
servers:
- url: https://go.aiinsurance.io
description: Production
security:
- ApiKeyAuth: []
paths:
/api/v1/companies/{companyId}/configuration/data-validation-runs/{runId}:
get:
tags:
- FMV1 Configuration
summary: Get Data Validation Run
description: >
Reports the progress and results of a **data validation run** started by
**`POST /configuration/data-validation-runs`**.
Poll this until `status` is `succeeded` or `failed`. The counts climb as
the scan
progresses, so a poll mid-scan is a real partial reading, not a
placeholder.
### Statuses
- **`queued`** — the run exists and is waiting for a worker. Its counts
are all
`0`. This is a normal state that every run passes through, **not** a stall: the
run is recorded before the background work is dispatched.
- **`running`** — the scan is in progress; the counts climb.
- **`succeeded`** — the whole book was scanned. `finishedAt` is set,
`error` is
`null`.
- **`failed`** — the scan stopped early. `finishedAt` is set and `error`
carries
the reason. Start a new run to retry.
### The counts
`recordsScanned` is how many records the scan has classified so far. The
other
three are **independent, overlapping** buckets — a record with an
undeclared key
*and* a value that breaks is counted in both, so **they do not sum to
`recordsScanned`**:
- **`recordsAdhering`** — records that would persist cleanly under the
scanned
configuration: no undeclared keys and no violations.
- **`recordsWithExtraKeys`** — records holding keys the scanned
configuration no
longer declares. Suspect, not necessarily fatal.
- **`recordsBreaking`** — records holding a value that would **fail** a
write
under the scanned configuration (a changed type or cardinality, an option-set
key that no longer exists, a broken relational reference, a violated
invariant).
There is deliberately **no total and no percentage**: producing a
denominator
would mean counting every record of every entity type before the scan
could
report anything. Treat `recordsScanned` as a monotonic progress signal,
and the
terminal `status` as completion.
Per-record detail — *which* records and *which* fields — is not part of
this
response.
### How long a run stays readable
A run's status stays readable for as long as the run exists — nothing
removes a
run on a timer, and however long ago it completed this endpoint still
reports
it. **A run's age is never a failure:** a run that exists is reported in
full
however long ago it finished, and no response reports a run as too old
to read.
**Required permission:** `company.configuration:export`
This endpoint requires an API key created with the
**FMV1_CONFIGURATION_MANAGER** role.
See [Authentication](/api-reference/authentication) for how to create
API keys with specific roles.
operationId: getFmv1DataValidationRun
parameters:
- $ref: '#/components/parameters/companyId'
- name: runId
in: path
required: true
schema:
type: string
format: uuid
description: >
The run identifier returned by **`POST
/configuration/data-validation-runs`**. Runs are scoped to their
company: a
run id belonging to another company returns `404`, exactly as an id
that
exists nowhere does.
responses:
'200':
description: The run's current status and running counts
content:
application/json:
schema:
$ref: '#/components/schemas/DataValidationRunResponse'
examples:
queued:
summary: Started, not yet claimed by a worker
value:
runId: 7c9e6679-7425-40de-944b-e07fc1f90ae7
status: queued
recordsScanned: 0
recordsAdhering: 0
recordsWithExtraKeys: 0
recordsBreaking: 0
error: null
createdAt: '2026-07-30T12:00:00.000Z'
updatedAt: '2026-07-30T12:00:00.000Z'
finishedAt: null
running:
summary: Mid-scan — the counts climb as records are classified
value:
runId: 7c9e6679-7425-40de-944b-e07fc1f90ae7
status: running
recordsScanned: 400
recordsAdhering: 388
recordsWithExtraKeys: 9
recordsBreaking: 5
error: null
createdAt: '2026-07-30T12:00:00.000Z'
updatedAt: '2026-07-30T12:00:07.500Z'
finishedAt: null
succeeded:
summary: The whole book was scanned
value:
runId: 7c9e6679-7425-40de-944b-e07fc1f90ae7
status: succeeded
recordsScanned: 1284
recordsAdhering: 1250
recordsWithExtraKeys: 27
recordsBreaking: 11
error: null
createdAt: '2026-07-30T12:00:00.000Z'
updatedAt: '2026-07-30T12:00:41.000Z'
finishedAt: '2026-07-30T12:00:41.000Z'
failed:
summary: The scan stopped early — start a new run to retry
value:
runId: 7c9e6679-7425-40de-944b-e07fc1f90ae7
status: failed
recordsScanned: 300
recordsAdhering: 300
recordsWithExtraKeys: 0
recordsBreaking: 0
error: >-
validate-entity-data: run 7c9e6679 failed: connection
reset
createdAt: '2026-07-30T12:00:00.000Z'
updatedAt: '2026-07-30T12:00:12.000Z'
finishedAt: '2026-07-30T12:00:12.000Z'
'400':
description: >
Bad Request - the run id path parameter is missing or is not a UUID.
A
well-formed id that belongs to no run of this company is a `404`,
not a
`400`.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
invalidRunId:
summary: Missing or malformed run id
value:
error:
code: INVALID_RUN_ID
message: A run id path parameter is required, and must be a UUID.
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
description: >
Not Found — no run with this id exists for this company. A run id
belonging
to a different company is reported the same way, so this response
never
reveals whether an id exists elsewhere. A run's age never produces
this
response: a run that exists is reported in full however long ago it
finished.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
notFound:
summary: Unknown run id for this company
value:
error:
code: NotFound
message: >-
Data-validation run 7c9e6679-7425-40de-944b-e07fc1f90ae7
not found.
'500':
$ref: '#/components/responses/InternalServerError'
security:
- BearerAuth: []
- ApiKeyAuth: []
components:
parameters:
companyId:
name: companyId
in: path
required: true
schema:
type: string
format: uuid
description: Company identifier
schemas:
DataValidationRunResponse:
type: object
description: >
A data-validation run's current status and running counts. Fixed size:
there is
no per-record findings list, and deliberately no total or percentage —
the three
classification counts are independent, overlapping buckets and do not
sum to
`recordsScanned`.
required:
- runId
- status
- recordsScanned
- recordsAdhering
- recordsWithExtraKeys
- recordsBreaking
- error
- createdAt
- updatedAt
- finishedAt
properties:
runId:
type: string
format: uuid
description: The run identifier
status:
type: string
enum:
- queued
- running
- succeeded
- failed
description: >-
`queued` while the run waits for a worker (a normal state, not a
stall), `running` mid-scan, then the terminal `succeeded` or
`failed`
recordsScanned:
type: integer
description: How many stored records the scan has classified so far
recordsAdhering:
type: integer
description: >-
Records that would persist cleanly under the scanned configuration —
no undeclared keys and no violations
recordsWithExtraKeys:
type: integer
description: >-
Records holding keys the scanned configuration no longer declares
(suspect, not necessarily fatal)
recordsBreaking:
type: integer
description: >-
Records holding a value that would FAIL a write under the scanned
configuration
error:
type: string
nullable: true
description: Why the scan stopped; null unless status is `failed`
createdAt:
type: string
format: date-time
description: When the run was started
updatedAt:
type: string
format: date-time
description: When the run's counts or status last changed
finishedAt:
type: string
format: date-time
nullable: true
description: When the run reached a terminal status; null until then
ErrorResponse:
type: object
description: Standard error response for all external API endpoints
required:
- error
properties:
error:
type: object
required:
- code
- message
properties:
code:
type: string
description: Machine-readable error code
example: VALIDATION_ERROR
message:
type: string
description: Human-readable error message
example: 'submissionId: Required field is missing'
userMessages:
type: array
description: >-
Clean, verbatim-displayable messages — one entry per failure,
free of error-code tags, field paths, and internal noise.
Suitable for showing to end users as-is.
items:
type: string
example:
- Exposures of type 'company' require an address
details:
type: array
description: Additional details for validation errors (field-level errors)
items:
type: object
properties:
field:
type: string
description: The field that caused the error
example: submissionId
message:
type: string
description: Description of the field error
example: Required field is missing
responses:
Unauthorized:
description: Unauthorized - Invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
missingApiKey:
summary: Missing API key
value:
error:
code: AuthenticationError
message: API key authentication required
userMessages:
- API key authentication required
invalidApiKey:
summary: >-
Invalid API key (e.g. unknown key, or a Bearer token used
instead of an API key)
value:
error:
code: AuthenticationError
message: Invalid API key
userMessages:
- Invalid API key
Forbidden:
description: Forbidden - Insufficient permissions
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
insufficientPermissions:
summary: Insufficient permissions
value:
error:
code: AuthorizationError
message: User is not authorized to perform the requested action
userMessages:
- User is not authorized to perform the requested action
companyMismatch:
summary: A valid API key naming another company in the URL
value:
error:
code: AuthorizationError
message: API key is not scoped to the requested company
userMessages:
- API key is not scoped to the requested company
InternalServerError:
description: Internal Server Error - Unexpected error occurred
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
internalError:
summary: Unexpected server error
value:
error:
code: UncaughtActionError
message: Uncaught error occurred in
userMessages:
- An unexpected error occurred. Please try again later.
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Authorization
description: >-
API key authentication. Send your raw API key as the `Authorization`
header value with NO scheme prefix — `Authorization: YOUR-API-KEY`. Do
NOT prefix it with `Bearer ` or `ApiKey `, and do not use an `X-API-Key`
header; those are not accepted.
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >-
User-principal OAuth 2.0 Bearer authentication. Send a user-scoped Auth0
access token (audience = the app API audience) as `Authorization: Bearer
`. The request resolves to the user's identity and is authorized by
their Role on the `{companyId}` in the path — the same role-based
permissions the web app enforces. This is the path the MCP connector
uses to act on a user's behalf; endpoints that accept it list both
`BearerAuth` and `ApiKeyAuth`.
````