---
title: "Get which scopes cover the files of a directory"
method: GET
path: "/orgs/{owner}/repositories/{repository}/scopes/coverage"
tags: ["scopes"]
---

# Get which scopes cover the files of a directory

`GET /orgs/{owner}/repositories/{repository}/scopes/coverage`

## Request

- Base URL: `https://api.mergify.com/v1`
- URL: `https://api.mergify.com/v1/orgs/{owner}/repositories/{repository}/scopes/coverage`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer
  - HTTP bearer
  - HTTP bearer

For one directory of the repository's default branch, which of its files the committed `scopes` hold, as the merge queue matches a pull request's changed files, in total and for each of its entries. The files are read from the branch once an hour at most.

Application key permission: `configuration: read`.

## Path parameters

- `repository` string, required: The name of the repository
- `owner` string, required: The owner of the repository

## Query parameters

- `path` string: The directory to describe, from the repository's root; empty for the root

## Headers

- `Mergify-Version` string, nullable: The API version the request is written against, a date (`YYYY-MM-DD`). Without it, a request made with an application key is served its organization's API version, and any other request 2026-11-16. A version this server does not serve is refused with a 400, the error code `API_VERSION_UNKNOWN` and the versions it serves in `served_versions`.

## Response `200`

Successful Response

- ScopesCoverage
  - `branch` string, required: The default branch the files are read from
  - `commit_sha` string, required: The commit of the branch the files are read from
  - `listed_at` string, date-time, required: When the files were read from the branch: they are read again once an hour at most
  - `truncated` boolean, required: Whether the repository holds more than the forge lists of a tree in one response (100,000 entries, directories included, or 7 MB on GitHub): the counts then cover only the files it listed
  - `path` string, required: The directory described: empty for the root, else ending with `/`
  - `files` integer, required: The files under the directory
  - `files_without_scope` integer, required: Of those, the files no scope holds
  - `files_in_all_scopes` integer, required: Of those, the files `barrier_files` matches
  - `entries` ScopesCoverageEntry[], required: The directory's entries, directories first, then by name, up to 1000
    - `name` string, required: The entry's name in its directory
    - `path` string, required: The entry's path from the repository's root
    - `type` 'directory' | 'file', required: Whether the entry is a directory or a file
    - `pattern` string, nullable, required: A scope glob holding this entry alone: the file, or every file under the directory. Null for a path holding a `\`, which a glob always reads as a separator
    - `files` integer, required: The files it holds: 1 for a file
    - `files_without_scope` integer, required: Of its files, those no scope holds and `barrier_files` leaves out: a pull request changing only such files belongs to no scope
    - `files_in_all_scopes` integer, required: Of its files, those `barrier_files` matches: a pull request changing one impacts every scope
    - `scopes` string[], required: The scopes that hold at least one of its files, in the order of the configuration, up to 1000
    - `scopes_omitted` integer, required: The scopes holding its files beyond the ones listed
  - `entries_omitted` integer, required: The entries beyond the ones listed

## Other responses

- `400`: `API_VERSION_UNKNOWN`: The `Mergify-Version` header names an API version this server does not serve. `served_versions` lists the versions it serves.
- `403`: Forbidden
- `404`: `SCOPES_COVERAGE_PATH_NOT_FOUND`: No file of the default branch is under the path, or the branch has no file yet.
- `409`: `SCOPES_COVERAGE_MANUAL_SOURCE`: The scopes come from CI reports (`source: manual`), so no file belongs to a scope by its path.
- `422`: `CONFIGURATION_INVALID`: The repository's Mergify configuration is invalid. `extended_repository` names the repository its `extends` points to when the error is in that repository's configuration file, and is null otherwise, including when the error only appears once the two configurations are merged. `SCOPES_COVERAGE_GLOB_TOO_COSTLY`: The globs of the scopes are too costly to match against the paths of the repository.
- `503`: `SCOPES_COVERAGE_UNAVAILABLE`: The files of the repository are still being listed.

## Changes

- **2026-11-20** `e6ed7cbf3cff`: 18 warning
  - added the new `PIPELINE_CACHE_STATS_INVALID_TIME_RANGE` enum value to the `anyOf[subschema #1: ConfigurationInvalidBody]/error_code` response property for the response status `422`
  - added the new `PIPELINE_CACHE_STATS_INVALID_TIME_RANGE` enum value to the `anyOf[subschema #2: APIErrorBody]/error_code` response property for the response status `422`
  - added the new `PIPELINE_CACHE_STATS_INVALID_TIME_RANGE` enum value to the `error_code` response property for the response status `400`
  - added the new `PIPELINE_CACHE_STATS_INVALID_TIME_RANGE` enum value to the `error_code` response property for the response status `404`
  - …14 more
- **2026-11-20** `e9a0452da665`: 54 warning
  - added the new `MERGE_QUEUE_POLICY_INVALID_PATTERN` enum value to the `anyOf[subschema #1: ConfigurationInvalidBody]/error_code` response property for the response status `422`
  - added the new `MERGE_QUEUE_POLICY_INVALID_PATTERN` enum value to the `anyOf[subschema #2: APIErrorBody]/error_code` response property for the response status `422`
  - added the new `MERGE_QUEUE_POLICY_INVALID_PATTERN` enum value to the `error_code` response property for the response status `400`
  - added the new `MERGE_QUEUE_POLICY_INVALID_PATTERN` enum value to the `error_code` response property for the response status `404`
  - …50 more
- …earlier changes not shown

[Operation history](https://skmtc.dev/mergify/apis/mergify-api/changes/orgs/:owner/repositories/:repository/scopes/coverage/get.md)

---

[API](https://skmtc.dev/mergify/apis/mergify-api.md) - [All operations](https://skmtc.dev/mergify/apis/mergify-api/llms.txt) - [OpenAPI document](https://skmtc.dev/mergify/apis/mergify-api/revisions/e6ed7cbf3cff?raw)
