> ## Documentation Index > Fetch the complete documentation index at: https://docs.generalvalidation.com/llms.txt > Use this file to discover all available pages before exploring further. # Prepare a Run > Freeze the Table Pair and its Tests into a new Run and return the values that start it in Fabric. Repeating the request with the same Run ID returns the same Run without its report token. Returns 402 without an active subscription or trial. Requires the GV.APIContributor application role, or a higher role (Owner > Contributor > Reader). ## OpenAPI ````yaml /api/openapi.json post /api/v1/fabric/runs openapi: 3.1.0 info: description: >- General Validation's API for Organization administration, Table Pair and Test authoring, Runs, and Result metadata. Microsoft Entra bearer tokens authorize every call. title: General Validation API version: 1.0.0 servers: - url: https://api.generalvalidation.com security: [] tags: - description: >- Customer-owned Fabric references, immutable Runs, and safe Result summaries. name: Fabric - description: Organizations and verified membership. name: Organization - description: Subscriptions and entitlements. name: Billing paths: /api/v1/fabric/runs: post: tags: - Fabric summary: Prepare a Run description: >- Freeze the Table Pair and its Tests into a new Run and return the values that start it in Fabric. Repeating the request with the same Run ID returns the same Run without its report token. Returns 402 without an active subscription or trial. Requires the GV.APIContributor application role, or a higher role (Owner > Contributor > Reader). operationId: prepare_fabric_run requestBody: content: application/json: schema: $ref: '#/components/schemas/RunPrepare' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/PreparedFabricRun' description: Successful Response '401': content: application/problem+json: schema: $ref: '#/components/schemas/V1Problem' description: A valid Microsoft Entra bearer token is required. '402': content: application/problem+json: schema: $ref: '#/components/schemas/V1Problem' description: The organization entitlement does not permit this mutation. '403': content: application/problem+json: schema: $ref: '#/components/schemas/V1Problem' description: The authenticated principal does not have the required role. '404': content: application/problem+json: schema: $ref: '#/components/schemas/V1Problem' description: The resource does not exist in this tenant. '409': content: application/problem+json: schema: $ref: '#/components/schemas/V1Problem' description: The operation conflicts with current resource or Azure state. '422': content: application/problem+json: schema: $ref: '#/components/schemas/V1Problem' description: The request is syntactically valid but semantically invalid. '429': content: application/problem+json: schema: $ref: '#/components/schemas/V1Problem' description: The bounded application request rate was exceeded. headers: Retry-After: description: Seconds to wait before retrying. schema: minimum: 1 type: integer '503': content: application/problem+json: schema: $ref: '#/components/schemas/V1Problem' description: A required dependency is temporarily unavailable. headers: Retry-After: description: Seconds to wait before retrying. schema: minimum: 1 type: integer security: - entraApplication: [] components: schemas: RunPrepare: additionalProperties: false properties: id: description: >- A new UUID you choose for the Run. Repeating the request with the same ID returns the same Run. format: uuid title: Id type: string pair_id: description: The Table Pair to run. It needs at least one Test. format: uuid title: Pair Id type: string required: - id - pair_id title: RunPrepare type: object PreparedFabricRun: properties: config: $ref: '#/components/schemas/RunConfig' description: The Table Pair and Tests this Run froze when it was prepared. created_at: title: Created At type: string error_code: anyOf: - enum: - submission_unknown - submission_rejected - no_report - fabric_job_failed - fabric_job_cancelled - invalid_arguments - invalid_config - run_reservation_failed - artifact_write_failed - summary_too_large - execution_failed type: string - type: 'null' description: >- Why the Run has no Result. `no_report` means nothing recorded a Result or failure within 7 days of preparing the Run; a Result recorded later still replaces it. title: Error Code id: format: uuid title: Id type: string job_id: anyOf: - format: uuid type: string - type: 'null' description: The Fabric job instance that runs it, once recorded. title: Job Id pair_id: description: The Table Pair this Run validates. format: uuid title: Pair Id type: string payload_base64: description: >- Pass unchanged as the validation pipeline's `payload_base64` parameter. Only `POST /api/v1/fabric/runs` returns it. title: Payload Base64 type: string provenance: const: user_reported default: user_reported description: >- Reported by an authorized caller; the SaaS does not attest the Fabric computation. title: Provenance type: string report: anyOf: - $ref: '#/components/schemas/RunReportCredential' - type: 'null' description: >- Pass `token` unchanged as the validation pipeline's `report_token` parameter. Returned only by the call that created the Run; a repeat with the same Run ID omits it. result: anyOf: - $ref: '#/components/schemas/RunResult' - type: 'null' description: The verdict and each Test's Result, once validation reports them. settings: $ref: '#/components/schemas/FabricSettings' description: The Environment the Run was prepared for. status: description: >- `prepared` or `submitted` while the Run is on its way; `passed`, `failed`, or `error` once it ends. enum: - prepared - submitted - passed - failed - error title: Status type: string updated_at: title: Updated At type: string required: - id - pair_id - status - config - settings - job_id - error_code - result - created_at - updated_at - payload_base64 title: PreparedFabricRun type: object V1Problem: additionalProperties: false properties: code: description: >- Stable machine-readable error code, such as `precondition.failed`. Branch on this value. title: Code type: string detail: description: What went wrong in this request, written for a person. title: Detail type: string diagnostics: anyOf: - additionalProperties: true type: object - type: 'null' default: null description: >- Extra details for some errors, such as `fieldErrors` for an invalid request or `requiredRole` for a denied one. Absent when there are none. title: Diagnostics instance: description: Path of the request that failed. title: Instance type: string requestId: description: >- This request's ID, also sent in the `X-Request-Id` response header. Quote it when you contact support. A request that sends an `X-Request-Id` of 1 to 64 letters, digits, or `_.:-` gets that value back. title: Requestid type: string status: description: The HTTP status code of this response. title: Status type: integer title: description: Short summary of the error code. title: Title type: string type: description: Link to the documentation page for this error code. title: Type type: string required: - type - title - status - code - detail - instance - requestId title: V1Problem type: object RunConfig: description: The Table Pair and Tests this Run froze when it was prepared. properties: {} required: [] title: RunConfig type: object RunReportCredential: additionalProperties: false properties: token: description: >- A secret that lets this Run's job report its outcome. Keep it out of logs. pattern: ^[0-9a-f]{64}$ title: Token type: string required: - token title: RunReportCredential type: object RunResult: description: The Run's verdict and each Test's Result. properties: pair_id: format: uuid title: Pair Id type: string results: description: One Result for each Test. items: $ref: '#/components/schemas/TestResult' maxItems: 100 minItems: 1 title: Results type: array run_id: format: uuid title: Run Id type: string status: description: >- `passed` when every Test passed, `failed` when a Test failed and none errored, and `error` when a Test errored. enum: - passed - failed - error title: Status type: string required: - run_id - pair_id - status - results title: RunResult type: object FabricSettings: additionalProperties: false properties: api_connection_id: description: >- The connection the validation pipeline uses to report each Run's outcome to General Validation. format: uuid title: Api Connection Id type: string lakehouse_id: description: >- The Results Lakehouse in that workspace, where Runs save exact values and mismatch evidence. format: uuid title: Lakehouse Id type: string pipeline_id: description: >- The validation pipeline. Start it with Fabric's job API to start a Run. format: uuid title: Pipeline Id type: string run_connection_id: description: >- The connection the validation pipeline uses to run the Spark Job Definition. format: uuid title: Run Connection Id type: string spark_job_definition_id: description: The Spark Job Definition that runs validation. format: uuid title: Spark Job Definition Id type: string workspace_id: description: The Environment's dedicated Fabric workspace. format: uuid title: Workspace Id type: string workspace_identity_id: description: >- The workspace identity's service principal object ID. Validation reads Tables as this identity. format: uuid title: Workspace Identity Id type: string required: - workspace_id - lakehouse_id - spark_job_definition_id - pipeline_id - run_connection_id - api_connection_id - workspace_identity_id title: FabricSettings type: object TestResult: additionalProperties: false properties: compared_count: anyOf: - maximum: 9007199254740991 minimum: 0 type: integer - type: 'null' description: How much the Test compared, when it counts that. title: Compared Count function: enum: - COUNT_ROWS - COUNT - COUNT_DISTINCT - MIN - MAX - AVG - SUM - VALUE - OUTER_VALUE - SET_A_IN_B - SET_B_IN_A - SET_A_EQUALS_B title: Function type: string mismatch_count: anyOf: - maximum: 9007199254740991 minimum: 0 type: integer - type: 'null' description: How many mismatches the Test found, when it counts them. title: Mismatch Count reason_code: description: Why the Test has this status. enum: - equal - different - no_common_keys - values_equal - values_differ - set_contained - set_not_contained - sets_equal - sets_differ - within_threshold - read_failed - copy_failed - copy_configuration_changed - connection_not_shared - column_name_refused - execution_failed - artifact_write_failed title: Reason Code type: string status: enum: - passed - failed - error title: Status type: string test_id: format: uuid title: Test Id type: string required: - test_id - function - status - reason_code title: TestResult type: object securitySchemes: entraApplication: bearerFormat: JWT description: >- Microsoft Entra application token issued by the caller's Organization tenant for this multitenant API. Request the .default scope and assign the application the required GV.APIReader, GV.APIContributor, or GV.APIOwner role. scheme: bearer type: http x-gv-app-roles: - GV.APIReader - GV.APIContributor - GV.APIOwner x-gv-audience: 78d5d8af-9dd6-49dd-b06c-38c3a3c707af x-gv-scope: api://78d5d8af-9dd6-49dd-b06c-38c3a3c707af/.default x-gv-token-url-template: https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.