---
title: "Get a filtered access point roster breakdown"
method: GET
path: "/v1/aps/{key}/roster-mix"
tags: ["Access Points"]
---

# Get a filtered access point roster breakdown

`GET /v1/aps/{key}/roster-mix`

## Request

- Base URL: `https://api.peppolstatus.com`
- URL: `https://api.peppolstatus.com/v1/aps/{key}/roster-mix`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

The five roster breakdowns of `GET /v1/aps/{key}` (country, entity type, NACE Rev. 2.1 division, size class, region) recomputed over a FILTERED slice of the roster, so a breakdown stays true while the roster is cut down. The filters are the same names and shapes as `GET /v1/participants`, scoped to this provider's seats.

BOUNDED BY DESIGN. The breakdowns are computed only when the filtered slice is narrow (under an internal cap of 10,000 participants). A request that narrows on nothing, that carries a filter this endpoint cannot express (`doctype`, `transport_profile`, `q`, `host`, `sub_provider`, `postcode`, `provenance`, `vat_liable`), or whose slice is too wide answers `degraded: true` with every mix null — never a wrong number and never an error. Callers fall back to the stored whole-roster mixes on `GET /v1/aps/{key}`.

Counts are sparse the same way the stored mixes are: company enrichment covers a handful of registers, so every mix except `country_mix` sums BELOW `participant_count` and the un-enriched remainder is derived from the total rather than served as a bucket.

A Vendor key (`v-<slug>`) answers the same question over the Vendor's roster and needs a Market-tier key. `seat` then selects one Seat the Vendor connects through.

## Path parameters

- `key` string, required

## Query parameters

- `seat` string
- `country` string[]
- `entity_type` string[]
- `sector` string[]
- `size` string[]
- `region` string[]
- `not_country` string[]
- `not_entity_type` string[]
- `not_sector` string[]
- `not_size` string[]
- `not_region` string[]
- `scheme` string[]
- `smp` string[]
- `registered` boolean

## Response `200`

The filtered roster breakdowns, or a degraded answer when they cannot be computed honestly.

- ApRosterMix: An access point's roster breakdowns over a filtered slice. Either computed (`degraded: false`, every field non-null) or degraded (`degraded: true`, every count and mix null) — the two states never mix.
  - `key` string, required: The canonical provider key (see ApView.key). Always the current one.
  - `degraded` boolean, required: True when the breakdowns could not be computed honestly — the request narrowed on nothing, carried a filter this endpoint cannot express, or selected a slice wider than the internal cap. Every mix and the count are then null and the caller falls back to the stored whole-roster mixes on GET /v1/aps/{key}.
  - `participant_count` integer, nullable, required: Exact size of the filtered slice (not an estimate, not capped). Null when degraded.
  - `country_mix` ApMixBucket[], nullable, required: Participants per country in the slice, count desc. Card country, falling back to the ICD-implied one.
    - `value` string, required
    - `count` integer, required
    - `label` string: Display label of `value`, on the buckets of a `size_mix` and a `region_mix` only: the English size band label (21 → "50–99 employees") and the region name in the local language (84 → "Auvergne-Rhône-Alpes"). Equal to `value` when the code is unknown. Filter on `value`.
  - `entity_type_mix` ApMixBucket[], nullable, required: Participants per company legal-form family in the slice, count desc. Sparse: sums below participant_count by the un-enriched remainder.
    - `value` string, required
    - `count` integer, required
    - `label` string: Display label of `value`, on the buckets of a `size_mix` and a `region_mix` only: the English size band label (21 → "50–99 employees") and the region name in the local language (84 → "Auvergne-Rhône-Alpes"). Equal to `value` when the code is unknown. Filter on `value`.
  - `sector_mix` ApMixBucket[], nullable, required: Participants per 2-digit NACE Rev. 2.1 division in the slice, count desc. Sparse.
    - `value` string, required
    - `count` integer, required
    - `label` string: Display label of `value`, on the buckets of a `size_mix` and a `region_mix` only: the English size band label (21 → "50–99 employees") and the region name in the local language (84 → "Auvergne-Rhône-Alpes"). Equal to `value` when the code is unknown. Filter on `value`.
  - `size_mix` ApMixBucket[], nullable, required: Participants per company size band code in the slice, count desc; each bucket carries its `label`. Sparse.
    - `value` string, required
    - `count` integer, required
    - `label` string: Display label of `value`, on the buckets of a `size_mix` and a `region_mix` only: the English size band label (21 → "50–99 employees") and the region name in the local language (84 → "Auvergne-Rhône-Alpes"). Equal to `value` when the code is unknown. Filter on `value`.
  - `region_mix` ApMixBucket[], nullable, required: Participants per company region code in the slice, count desc; each bucket carries its `label`. Sparse.
    - `value` string, required
    - `count` integer, required
    - `label` string: Display label of `value`, on the buckets of a `size_mix` and a `region_mix` only: the English size band label (21 → "50–99 employees") and the region name in the local language (84 → "Auvergne-Rhône-Alpes"). Equal to `value` when the code is unknown. Filter on `value`.

## Other responses

- `400`: An invalid `country` / `not_country` code, `registered`, or a multi-valued `seat`.
- `404`: No such access point is known.

---

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