Reference

Findings export

Download filtered project findings with report, CWE, and file provenance

Endpoint

GET /v1/projects/{projectId}/findings/export?profile=security|bugs|all

Needs a session or bearer token that can read the project. The UI calls this from Findings → Export JSON and downloads thespider-findings-project-{projectId}.json.

Query parameters

Parameter	Type	Description
`profile`	string	`security`, `bugs`, or explicit aggregate `all`. Omission uses the project default.
`campaignId`	integer	Include live findings sighted in this campaign.
`status`	string	One or more persisted finding statuses, comma-separated. Also accepts the `open`, `actionable`, and `closed` aliases.
`severity`	string	One or more canonical severity or impact values, comma-separated. Also accepts the reserved token `none`.
`bucket`	string	Match a bucket code.
`category`	string	Match findings with a report in this category.
`branch`	string	Match findings sighted on this branch.
`q`	string	Case-insensitive title, fingerprint, or bucket search.
`sort`	string	`priority` (default), `updated_desc`, `updated_asc`, or `title`.

Filters combine with AND. The endpoint ignores list pagination fields and returns the complete filtered set up to the export safety limit.

Status and severity filters

Same rules as GET /v1/projects/{projectId}/findings. Comma-separated lists, trimmed, de-duplicated.

GET /v1/projects/{projectId}/findings/export?status=open&severity=critical,high

Alias	Meaning
`open`	Everything except `fixed` and `false_positive`
`actionable`	Everything except `wont_fix`, `false_positive`, `accepted`, and `fixed` (what the PR gate still blocks on)
`closed`	Exactly `fixed` or `false_positive`

accepted and wont_fix stay open but drop out of actionable. Aliases and literal statuses mix (status=actionable,accepted) as a union.

severity=none matches unclassified findings. severity=critical,high excludes them; add none to include them. Unknown tokens match literally and usually return nothing.

filters in the response echoes the raw query strings ("open", "critical,high"), not the expanded set. That echo is part of schema version 1.

Response

{
  "schemaVersion": 1,
  "exportedAt": "2026-07-22T12:00:00.000Z",
  "project": {
    "id": 42,
    "slug": "payments-api",
    "name": "Payments API",
    "default_profile": "security"
  },
  "profile": "security",
  "filters": {
    "campaignId": "81",
    "severity": "high"
  },
  "mergedFindingsIncluded": false,
  "total": 1,
  "findings": [
    {
      "id": 501,
      "canonical_title": "Authorization missing on refund",
      "canonical_severity": "high",
      "status": "new",
      "fingerprint": "…",
      "bucket_code": "auth",
      "reports": [
        {
          "id": 702,
          "model_code": "anthropic/claude-sonnet-5",
          "pass_code": "http",
          "categories": ["authz"],
          "cwes": ["CWE-862"],
          "files": [
            { "path": "src/refunds.ts", "line": 88 }
          ],
          "evidence": "…",
          "impact": "…",
          "recommendation": "…"
        }
      ]
    }
  ]
}

The export includes canonical project-global finding status and only report/sighting provenance that matches the selected profile. In all, first-discovery bucket provenance is canonical and each finding includes profiles seen. Model-derived strings remain plain JSON strings.

Identity and merge behavior

The export includes live keeper findings only. Soft-merged tombstones are excluded, and mergedFindingsIncluded is always false in schema version 1. Reports absorbed by a keeper appear under that keeper.

Campaign filtering uses finding sightings. It does not filter by the campaign where a finding was first created.

Size behavior

A filtered export can contain at most 20,000 findings. A larger result returns:

413 export_too_large

Narrow the request with campaignId, severity, status, bucket, category, branch, or search filters. The endpoint returns one JSON document and does not paginate or create an asynchronous export job.

Errors

Status	Error	Meaning
`400`	`invalid_project_id`	The path identifier is not an integer.
`401`	authentication error	No valid session or bearer token.
`404`	`project_not_found`	The project does not exist in the authenticated tenant or token scope.
`413`	`export_too_large`	More than 20,000 findings match.
`429`	`rate_limited`	Request budget exhausted.

Use the triage guide for finding lifecycle behavior and the concepts glossary for keeper, merge, and sighting definitions.

Runner contract

Exact process, marker, output, timeout, and result-submission behavior for model runners

Agent CLI contracts

Stable JSON envelope, exit codes, and markdown packet format for thespider-agent findings, wait, and refine