List Package Runs

List matching package runs for your organization, filterable by package config and status, with cursor-based pagination.

List the matching package runs that belong to your organization. Results are cursor-paginated and ordered newest first by default. Each entry is the full run shape, including its aggregated status, per-type document results, and the document ids that were supplied.

You can narrow the list with two filters. Pass package_config_id to return only runs of a specific config, and pass status to return only runs with a given verdict, such as passed or review. Combine both to find, for example, every failing run of one package config.

Pagination follows the same cursor pattern used across the API. The pagination block carries total, limit, has_more, and next_cursor. Pass next_cursor back as the cursor query parameter to page forward. Every run is tenant-scoped to your organization.

GET/v1/matching/packages/runs

Response

Response fields

dataarrayArray of package run objects.

data[].idstringPackage run UUID.

data[].package_config_idstringUUID of the config this run scored against.

data[].statusstringAggregated verdict: passed, failed, review, error, or running.

data[].document_resultsarrayPer-document-type results.

data[].input_documentsobjectDocument ids supplied per type.

data[].errorstring | nullError detail when status is error.

data[].created_atstringISO 8601 creation timestamp.

data[].completed_atstring | nullISO 8601 completion timestamp.

data[].linksobjectRelated resource URLs (self, config).

pagination.totalintegerTotal number of runs matching the query.

pagination.limitintegerMaximum results per page.

pagination.has_morebooleanWhether more results exist beyond this page.

pagination.next_cursorstring | nullCursor to fetch the next page. Null if no more results.

Response

{
  "data": [
    {
      "id": "run_b2c3d4e5-f6a7-8901-bcde-f23456789012",
      "package_config_id": "pkg_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "status": "passed",
      "document_results": [
        {
          "document_type": "invoice",
          "matching_config_id": "mc_uuid_1",
          "matching_run_id": "mr_uuid_1",
          "presence": "required",
          "document_found": true,
          "status": "matched",
          "confidence": 0.93
        }
      ],
      "input_documents": { "invoice": ["doc_uuid_1"] },
      "error": null,
      "created_at": "2024-09-14T10:40:00.000Z",
      "completed_at": "2024-09-14T10:40:03.000Z",
      "links": {
        "self": "/v1/matching/packages/runs/run_b2c3d4e5-f6a7-8901-bcde-f23456789012",
        "config": "/v1/matching/packages/configs/pkg_a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      }
    }
  ],
  "pagination": {
    "total": 12,
    "limit": 20,
    "has_more": false,
    "next_cursor": null
  }
}

Combine package_config_id and status to triage runs: filter to one config with status=review to surface exactly the bundles a reviewer needs to look at.

Errors

Error responses

401unauthorizedMissing or invalid API key.

429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Trigger Package Run

Get Package Config