> ## Documentation Index > Fetch the complete documentation index at: https://api-docs.nunu.ai/llms.txt > Use this file to discover all available pages before exploring further. # Export to TestRail > Export runs or a test-plan execution using your project’s saved TestRail integration **Permission required:** `project:operate-runs`. TestRail must be enabled and configured for the project, with TestRail case mappings for the results you want to export. Export one nunu multiplayer run, several runs from the same project, or the completed runs in a test-plan execution. The export uses your project's saved TestRail connection and suite configuration. Results spanning multiple suites create a TestRail plan; a single suite creates a TestRail run. ## Request body Supply **exactly one** source: `multiplayer_run_id`, `multiplayer_run_ids`, or `test_plan_execution_id`. Unknown fields are rejected. Export one run. nunu multiplayer run ID from [List Runs](/api-reference/runs/list-runs). Do not use a job ID or per-player run ID. Export several runs together into one TestRail entry. 1 to 100 unique multiplayer run IDs from [List Runs](/api-reference/runs/list-runs), all in the same project. Execution ID from [List Test Plan Executions](/api-reference/test-plans/list-test-plan-executions), not the test-plan definition ID. Only completed runs in the execution are exported. Optional. Name for the created TestRail run or plan, replacing the generated `nunu.ai` name. Must contain 1 to 250 characters after trimming whitespace. Optional. Close the created TestRail run or plan after results are submitted. Set to `false` to leave it open. Optional. Create a new TestRail entry even when the test-plan execution was already exported. Set to `false` to return the existing TestRail links instead. Run exports always create a new entry. ## Existing exports and retries Every call creates a new TestRail entry by default. To avoid duplicating a test-plan export, send `force_new_run: false`: if the execution already has a saved TestRail export, the response includes `already_exported: true` and the existing IDs and links. No results are submitted again; `runs_processed` is empty and `total_test_cases` is `0`. Concurrent exports of the same execution return `409` while an export is in progress. An export performed before the execution finishes contains only the runs completed at that time. Do not blindly retry after a timeout: the remote entry may already exist. Inspect TestRail before submitting another export, or use `force_new_run: false` for test-plan executions. ## Response The response is the export result directly, without a `data` or `result` wrapper. It includes `success`, `export_type`, `export_trigger`, `export_strategy`, `runs_processed`, and `total_test_cases`. Depending on the suite configuration, the result includes `testrail_run_id` and `testrail_run_url`, or `testrail_plan_id` and `testrail_plan_url`. Names and `export_duration_ms` may also be present. Inspect optional `skipped_cases` and `warnings` for omitted cases or other export issues. Warning fields use `snake_case`, including `run_id` and `test_version_id`. Missing sources and sources belonging to another project both return `404`, including when any ID in `multiplayer_run_ids` is not found in the project. Invalid input returns `400`; missing permissions or a disabled TestRail integration returns `403`. ## Using MCP The matching MCP tool is `export_testrail_run`. It accepts the same body fields and returns the same export result, with identical duplicate-export behavior. Both API and MCP exports use a manual trigger; callers cannot select the internal automatic completion trigger. For global MCP, the run or test-plan execution IDs you supply identify the owning project, so `project_id` is not required even when your credentials can access several projects. You may still pass it, in which case it is checked against the project that owns the source: a value that does not match returns a `project_scope_mismatch` error naming both projects. Project-scoped MCP uses the project from its context. MCP accepts authorized user or API-key credentials; this HTTP endpoint accepts API keys. Both require `project:operate-runs`. Example global MCP tool arguments: ```json theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} { "test_plan_execution_id": "ffb62f53-7971-488b-a788-f57f2e967f62", "custom_run_name": "CI regression" } ``` The legacy `POST /api/v1/runs/export/testrail` endpoint accepts project API keys only and infers the project from the key. Organization API keys must use `/api/v1/project/{projectId}/runs/export/testrail`. ```bash cURL theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} curl -X POST "https://nunu.ai/api/v1/project/your-project-id/runs/export/testrail" \ -H "X-Api-Key: YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"multiplayer_run_id":"nunu-multiplayer-run-id","custom_run_name":"CI regression"}' ``` ```json 200 Success theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} { "success": true, "testrail_run_id": 123, "testrail_run_name": "CI regression", "testrail_run_url": "https://example.testrail.io/index.php?/runs/view/123", "export_type": "single_run", "export_trigger": "manual", "export_strategy": "single_suite", "runs_processed": ["nunu-multiplayer-run-id"], "total_test_cases": 4, "warnings": [] } ``` ```json 409 Export in progress theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} { "error": "an export for this test plan is already in progress" } ``` ## OpenAPI ````yaml POST /project/{projectId}/runs/export/testrail openapi: 3.1.0 info: title: nunu.ai API description: >- The nunu.ai Public API allows you to programmatically interact with your projects, manage test runs, and upload builds. version: 1.0.0 servers: - url: https://nunu.ai/api/v1 security: - apiKeyAuth: [] paths: /project/{projectId}/runs/export/testrail: parameters: - name: projectId in: path required: true schema: type: string description: >- The project ID. You can copy it from the project settings page or the project URL in the dashboard. post: tags: - Runs summary: Export to TestRail description: >- Export one nunu multiplayer run, several runs from the same project, or the completed runs in a test-plan execution using the saved TestRail integration. Requires project:operate-runs and TestRail enabled. Every call creates a new TestRail entry by default; send force_new_run: false to reuse an existing test-plan export. Do not blindly retry after a timeout. operationId: exportTestrailRun requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ExportTestrailRequest' responses: '200': description: Export completed, or existing test-plan export returned content: application/json: schema: $ref: '#/components/schemas/ExportTestrailResponse' '400': description: Invalid JSON or input; supply exactly one source content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Insufficient project permissions or TestRail is not enabled content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: >- Project or export source not found in the authorized project, including any run in multiplayer_run_ids content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: An export for this test-plan execution is already in progress content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Export or data access failed content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: ExportTestrailRequest: description: >- Supply exactly one source: multiplayer_run_id, multiplayer_run_ids, or test_plan_execution_id. Uses the saved project TestRail integration and a manual export trigger. Unknown fields are rejected. oneOf: - title: Single run type: object additionalProperties: false required: - multiplayer_run_id properties: multiplayer_run_id: type: string minLength: 1 description: >- nunu multiplayer run ID from List Runs. Not a job ID or a per-player run ID. custom_run_name: type: string minLength: 1 maxLength: 250 description: >- Optional. Name for the created TestRail run or plan. Leading and trailing whitespace is trimmed. Defaults to a generated nunu.ai name. close_run_on_completion: type: boolean default: true description: >- Optional. Close the created TestRail run or plan after results are submitted. Set false to leave it open. force_new_run: type: boolean default: true description: >- Optional. Create a new TestRail entry even if a test-plan execution was already exported. Set false to return the existing links with already_exported: true instead. - title: Multiple runs type: object additionalProperties: false required: - multiplayer_run_ids properties: multiplayer_run_ids: type: array minItems: 1 maxItems: 100 uniqueItems: true items: type: string minLength: 1 description: >- 1 to 100 unique nunu multiplayer run IDs from List Runs, all in the same project. Exported together into one TestRail entry. custom_run_name: type: string minLength: 1 maxLength: 250 description: >- Optional. Name for the created TestRail run or plan. Leading and trailing whitespace is trimmed. Defaults to a generated nunu.ai name. close_run_on_completion: type: boolean default: true description: >- Optional. Close the created TestRail run or plan after results are submitted. Set false to leave it open. force_new_run: type: boolean default: true description: >- Optional. Create a new TestRail entry even if a test-plan execution was already exported. Set false to return the existing links with already_exported: true instead. - title: Test plan execution type: object additionalProperties: false required: - test_plan_execution_id properties: test_plan_execution_id: type: string format: uuid description: >- Execution ID from List Test Plan Executions, not the test-plan definition ID. Exports the completed runs in this execution. custom_run_name: type: string minLength: 1 maxLength: 250 description: >- Optional. Name for the created TestRail run or plan. Leading and trailing whitespace is trimmed. Defaults to a generated nunu.ai name. close_run_on_completion: type: boolean default: true description: >- Optional. Close the created TestRail run or plan after results are submitted. Set false to leave it open. force_new_run: type: boolean default: true description: >- Optional. Create a new TestRail entry even if a test-plan execution was already exported. Set false to return the existing links with already_exported: true instead. ExportTestrailResponse: type: object required: - success - export_type - export_trigger - export_strategy - runs_processed - total_test_cases properties: success: type: boolean already_exported: type: boolean description: >- True when an existing test-plan export is returned without creating a new remote entry. export_duration_ms: type: number export_type: type: string enum: - single_run - test_plan - multiple_runs description: This endpoint accepts single_run or test_plan sources. export_trigger: type: string enum: - manual - auto description: Always manual for this endpoint. export_strategy: type: string enum: - single_suite - multi_suite_plan runs_processed: type: array items: type: string description: >- nunu multiplayer run IDs processed by this export. Empty when already_exported is true. skipped_cases: type: array items: type: number description: TestRail case IDs skipped during export. total_test_cases: type: number description: >- Number of aggregated TestRail cases. Zero when returning an existing export. warnings: type: array items: $ref: '#/components/schemas/ExportTestrailWarning' error: type: string error_code: type: string testrail_run_id: type: number testrail_run_name: type: string testrail_run_url: type: string testrail_plan_id: type: number testrail_plan_name: type: string testrail_plan_url: type: string Error: type: object properties: error: type: string code: type: string details: type: object ExportTestrailWarning: type: object required: - type - message properties: type: type: string description: Warning category. message: type: string description: Human-readable warning. run_id: type: string description: Affected nunu multiplayer run ID, when applicable. test_version_id: type: string description: Affected test version ID, when applicable. details: type: string description: Additional warning details. securitySchemes: apiKeyAuth: type: apiKey in: header name: X-Api-Key description: API key for authentication ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.