# Context

Retrieve structured test failure context for AI debugging.

The Context endpoint provides test failure data in JSON or Markdown format, suitable for feeding into AI tools and MCP integrations. It supports three detail levels:

* **Run-level**: Summary of all failures across a run
* **Instance-level**: Failures within a single spec file
* **Test-level**: Full detail for a single test attempt

## Get test failure context

> Retrieve structured test failure context for AI debugging. One of three query shapes is used:\
> \
> \- \*\*Run-level:\*\* \`run\_id\` only (omit \`instance\_id\` and \`test\_id\`). Paginate failed tests with \`limit\` and \`page\`.\
> \- \*\*Instance-level:\*\* \`run\_id\` and \`instance\_id\` (omit \`test\_id\`). Paginate with \`limit\` and \`page\`.\
> \- \*\*Test-level:\*\* \`instance\_id\` and \`test\_id\`. The run is resolved server-side from the instance; optional \`run\_id\` is ignored for lookup. Optional \`attempt\` selects a specific attempt; omit for the latest.

```json
{"openapi":"3.0.2","info":{"title":"Currents REST API","version":"1.0.0"},"tags":[{"name":"Context","description":"Retrieve structured test failure context for AI debugging.\n\nThe Context endpoint provides test failure data in JSON or Markdown format, suitable for feeding into AI tools and MCP integrations. It supports three detail levels:\n- **Run-level**: Summary of all failures across a run\n- **Instance-level**: Failures within a single spec file\n- **Test-level**: Full detail for a single test attempt"}],"servers":[{"url":"https://api.currents.dev/v1","description":"Production API"},{"url":"https://api-staging.currents.dev/v1","description":"Staging API"},{"url":"http://localhost:4000/v1","description":"Local development"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key authentication using Bearer token"}},"schemas":{"ContextResponse":{"type":"object","required":["status","data"],"properties":{"status":{"type":"string","enum":["OK"]},"data":{"oneOf":[{"$ref":"#/components/schemas/ContextTestData"},{"$ref":"#/components/schemas/ContextInstanceData"},{"$ref":"#/components/schemas/ContextRunData"}],"discriminator":{"propertyName":"level","mapping":{"test":"#/components/schemas/ContextTestData","instance":"#/components/schemas/ContextInstanceData","run":"#/components/schemas/ContextRunData"}}}}},"ContextTestData":{"type":"object","required":["level","spec","test","error","meta","environment"],"properties":{"level":{"type":"string","enum":["test"]},"spec":{"type":"string","description":"Spec file path"},"test":{"type":"object","properties":{"title":{"type":"array","items":{"type":"string"},"description":"Test title hierarchy"},"status":{"type":"string"},"attempt":{"type":"integer"},"totalAttempts":{"type":"integer"},"duration":{"type":"integer","description":"Duration in milliseconds"}}},"error":{"$ref":"#/components/schemas/ContextError"},"otherAttempts":{"type":"array","description":"Summary of other attempts for cross-attempt comparison","items":{"type":"object","properties":{"attempt":{"type":"integer"},"status":{"type":"string"},"sameError":{"type":"boolean","description":"Whether this attempt had the same error as the displayed attempt"},"error":{"type":"object","nullable":true,"description":"Simplified error summary (no stack/snippet)","properties":{"message":{"type":"string","nullable":true},"location":{"$ref":"#/components/schemas/ContextErrorLocation"}}}}}},"errorContext":{"allOf":[{"$ref":"#/components/schemas/ContextAsset"}],"nullable":true,"description":"Browser accessibility snapshot at time of failure (signed URL)"},"traceErrorAnalysis":{"type":"object","nullable":true,"description":"Console entries and network requests from the error timeframe","properties":{"consoleEntries":{"type":"array","items":{"type":"object","properties":{"time":{"type":"number"},"messageType":{"type":"string"},"text":{"type":"string"},"location":{"type":"object","nullable":true,"properties":{"url":{"type":"string"},"lineNumber":{"type":"integer"},"columnNumber":{"type":"integer"}}}}}},"networkRequests":{"type":"array","items":{"type":"object","properties":{"time":{"type":"number"},"url":{"type":"string"},"status":{"type":"integer"},"method":{"type":"string"}}}}}},"failureContext":{"$ref":"#/components/schemas/ContextFailureContext"},"steps":{"type":"array","description":"Test execution steps (omitted when detail=summary)","items":{"$ref":"#/components/schemas/ContextStep"}},"stdout":{"type":"array","items":{"type":"string"},"description":"Standard output lines from the test"},"stderr":{"type":"array","items":{"type":"string"},"description":"Standard error lines from the test"},"assets":{"type":"object","description":"Signed URLs for traces, screenshots, videos, and attachments","properties":{"traces":{"type":"array","items":{"$ref":"#/components/schemas/ContextAsset"}},"screenshots":{"type":"array","items":{"$ref":"#/components/schemas/ContextAsset"}},"videos":{"type":"array","items":{"$ref":"#/components/schemas/ContextAsset"}},"attachments":{"type":"array","items":{"type":"object","description":"Attachment with additional metadata","properties":{"name":{"type":"string"},"filename":{"type":"string"},"contentType":{"type":"string"},"url":{"type":"string","description":"Signed URL to the attachment"}}}},"totals":{"type":"object","nullable":true,"description":"Total counts for each asset category. Only present when assets are limited (detail=compact or detail=summary)","properties":{"traces":{"type":"integer","description":"Total number of traces before limiting"},"screenshots":{"type":"integer","description":"Total number of screenshots before limiting"},"videos":{"type":"integer","description":"Total number of videos before limiting"},"attachments":{"type":"integer","description":"Total number of attachments before limiting"}}}}},"meta":{"type":"object","properties":{"projectId":{"type":"string"},"runId":{"type":"string"},"instanceId":{"type":"string"},"testId":{"type":"string"},"signature":{"type":"string"},"attempt":{"type":"integer"}}},"environment":{"type":"object","properties":{"framework":{"$ref":"#/components/schemas/ContextFramework"},"platform":{"$ref":"#/components/schemas/ContextPlatform"},"project":{"type":"string","nullable":true}}}}},"ContextError":{"type":"object","nullable":true,"description":"Error details including message, stack, location, and code snippet","properties":{"message":{"type":"string","nullable":true},"stack":{"type":"string","nullable":true},"location":{"$ref":"#/components/schemas/ContextErrorLocation"},"snippet":{"type":"string","nullable":true,"description":"Code snippet around the error location"}}},"ContextErrorLocation":{"type":"object","nullable":true,"description":"Source code location of an error","properties":{"file":{"type":"string"},"line":{"type":"integer"},"column":{"type":"integer"}}},"ContextAsset":{"type":"object","description":"A signed URL reference to an asset","properties":{"name":{"type":"string"},"url":{"type":"string","description":"Signed URL to the asset"}}},"ContextFailureContext":{"type":"object","nullable":true,"description":"Context around the failed step","properties":{"failedStepIndex":{"type":"integer","description":"Index of the failed step in the flattened steps array (0-indexed)"},"stepBefore":{"allOf":[{"$ref":"#/components/schemas/ContextStep"}],"nullable":true,"description":"The step that executed before the failure (null if failed step was first)"},"failedStep":{"$ref":"#/components/schemas/ContextStep","description":"The step that failed"},"stepAfter":{"allOf":[{"$ref":"#/components/schemas/ContextStep"}],"nullable":true,"description":"The step that would have executed after (null if failed step was last)"}}},"ContextStep":{"type":"object","description":"A test execution step (recursive structure)","properties":{"title":{"type":"string","description":"Step title/description"},"category":{"type":"string","description":"Step category (e.g., pw:api)"},"duration":{"type":"integer","description":"Duration in milliseconds"},"error":{"$ref":"#/components/schemas/ContextError"},"steps":{"type":"array","description":"Nested child steps","items":{"$ref":"#/components/schemas/ContextStep"}}}},"ContextFramework":{"type":"object","nullable":true,"description":"Test framework information","properties":{"type":{"type":"string","description":"Framework type (e.g., playwright, cypress)"},"version":{"type":"string","nullable":true}}},"ContextPlatform":{"type":"object","nullable":true,"description":"Platform/browser information","properties":{"osName":{"type":"string"},"osVersion":{"type":"string"},"browserName":{"type":"string"},"browserVersion":{"type":"string"}}},"ContextInstanceData":{"type":"object","required":["level","spec","instanceStatus","instanceAssets","list","count","total","nextPage","meta","environment"],"properties":{"level":{"type":"string","enum":["instance"]},"spec":{"type":"string"},"instanceStatus":{"type":"string","description":"Instance lifecycle status (FAILED, TIMED_OUT, CANCELLED, etc.)"},"instanceAssets":{"type":"object","description":"Instance-level assets","properties":{"stdout":{"allOf":[{"$ref":"#/components/schemas/ContextAsset"}],"nullable":true,"description":"Signed URL to instance stdout"}}},"list":{"type":"array","description":"Failed tests on this page","items":{"allOf":[{"$ref":"#/components/schemas/ContextFailedTestBase"},{"type":"object","properties":{"totalAttempts":{"type":"integer"}}}]}},"count":{"type":"integer","description":"Number of items in `list` for this page"},"total":{"type":"integer","description":"Total number of failed tests for the instance"},"nextPage":{"oneOf":[{"type":"integer"},{"type":"boolean","enum":[false]}],"description":"Next page index (0-based), or false if no more pages"},"meta":{"type":"object","properties":{"projectId":{"type":"string"},"runId":{"type":"string"},"instanceId":{"type":"string"}}},"environment":{"type":"object","properties":{"framework":{"$ref":"#/components/schemas/ContextFramework"},"platform":{"$ref":"#/components/schemas/ContextPlatform"},"project":{"type":"string","nullable":true}}}}},"ContextFailedTestBase":{"type":"object","description":"Common properties for failed test summaries","properties":{"testId":{"type":"string"},"title":{"type":"array","items":{"type":"string"},"description":"Test title hierarchy"},"status":{"type":"string"},"attempt":{"type":"integer"},"duration":{"type":"integer","description":"Duration in milliseconds"},"error":{"$ref":"#/components/schemas/ContextError"},"errorContext":{"allOf":[{"$ref":"#/components/schemas/ContextAsset"}],"nullable":true,"description":"Browser accessibility snapshot at time of failure"},"failureContext":{"$ref":"#/components/schemas/ContextFailureContext"},"detailUrl":{"type":"string","description":"Absolute URL for full test-level context"}}},"ContextRunData":{"type":"object","required":["level","runId","runStatus","instances","list","count","total","nextPage","meta","environment"],"properties":{"level":{"type":"string","enum":["run"]},"runId":{"type":"string"},"runStatus":{"type":"string"},"instances":{"type":"array","description":"All non-passed instances in the run","items":{"type":"object","properties":{"instanceId":{"type":"string"},"spec":{"type":"string"},"status":{"type":"string"},"durationMs":{"type":"integer","nullable":true},"groupId":{"type":"string","nullable":true}}}},"list":{"type":"array","description":"Paginated unique failing tests (deduplicated by signature + error)","items":{"allOf":[{"$ref":"#/components/schemas/ContextFailedTestBase"},{"type":"object","properties":{"instanceId":{"type":"string"},"spec":{"type":"string"},"groupId":{"type":"string","nullable":true},"alsoFailedIn":{"type":"array","description":"Other tests with the same error (cross-group deduplication)","items":{"type":"object","properties":{"testId":{"type":"string"},"instanceId":{"type":"string"},"groupId":{"type":"string"},"title":{"type":"array","items":{"type":"string"},"description":"Test title for context"}}}}}}]}},"count":{"type":"integer","description":"Number of items in `list` for this page"},"total":{"type":"integer","description":"Unique failing tests after deduplication (may be subset on large runs)"},"nextPage":{"oneOf":[{"type":"integer"},{"type":"boolean","enum":[false]}],"description":"Next page index (0-based), or false if no more pages"},"meta":{"type":"object","properties":{"projectId":{"type":"string"},"runId":{"type":"string"}}},"environment":{"type":"object","properties":{"framework":{"$ref":"#/components/schemas/ContextFramework"}}}}},"ErrorResponse":{"type":"object","required":["status","error"],"properties":{"status":{"type":"string","enum":["FAILED"]},"error":{"type":"string","description":"Error message"}}}},"responses":{"BadRequest":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/context":{"get":{"summary":"Get test failure context","description":"Retrieve structured test failure context for AI debugging. One of three query shapes is used:\n\n- **Run-level:** `run_id` only (omit `instance_id` and `test_id`). Paginate failed tests with `limit` and `page`.\n- **Instance-level:** `run_id` and `instance_id` (omit `test_id`). Paginate with `limit` and `page`.\n- **Test-level:** `instance_id` and `test_id`. The run is resolved server-side from the instance; optional `run_id` is ignored for lookup. Optional `attempt` selects a specific attempt; omit for the latest.","operationId":"getContext","tags":["Context"],"parameters":[{"name":"run_id","in":"query","required":false,"description":"Run identifier. Required for run-level (`run_id` only) and instance-level (`run_id` + `instance_id`, no `test_id`). For test-level (`instance_id` + `test_id`), ignored; the server resolves the run from the instance.","schema":{"type":"string"}},{"name":"instance_id","in":"query","required":false,"description":"Instance identifier. Required for instance-level and test-level. Omit for run-level (use `run_id` only).","schema":{"type":"string"}},{"name":"test_id","in":"query","required":false,"description":"Test identifier. When set, selects test-level detail and requires `instance_id`.","schema":{"type":"string"}},{"name":"attempt","in":"query","required":false,"description":"Attempt number (0-indexed); defaults to latest","schema":{"type":"integer"}},{"name":"format","in":"query","required":false,"description":"Response format. Falls back to Accept header when absent.","schema":{"type":"string","enum":["json","md"],"default":"json"}},{"name":"detail","in":"query","required":false,"description":"Controls output verbosity to limit token count. 'default' returns all available data. 'compact' reduces output size by omitting the full steps array and limiting assets to 3 per category while preserving failure context and analysis. 'summary' minimizes output by including only error info and metadata.","schema":{"type":"string","enum":["default","compact","summary"],"default":"default"}},{"name":"limit","in":"query","required":false,"description":"Maximum number of failed tests per page (run-level and instance-level only)","schema":{"type":"integer","default":10,"minimum":1,"maximum":50}},{"name":"page","in":"query","required":false,"description":"Page number for failed tests pagination, 0-indexed (run-level and instance-level only)","schema":{"type":"integer","default":0,"minimum":0}},{"name":"max_length","in":"query","required":false,"description":"Truncate markdown response to this character limit (only applies when format=md). Useful for fitting context into AI prompts.","schema":{"type":"integer","minimum":1,"maximum":50000}}],"responses":{"200":{"description":"Context data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContextResponse"}},"text/markdown":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.currents.dev/api/resources/context.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.