> ## Documentation Index
> Fetch the complete documentation index at: https://developers.mypilotindex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Insights

> Read the pilot workforce as a market, and show one pilot where they stand among their peers.

Insights come in two reads. A partner with `insights.read` reads the Workforce: what the pilots of MyPilotIndex look like as a market, in aggregates. A pilot app with a grant that holds `insights.position` reads where one pilot stands against that pilot's cohort.

## Read the Workforce

```bash theme={null}
curl "https://{api-host}/v1/partner/insights/workforce/overview?country=BR" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

```json theme={null}
{
  "schema_version": 1,
  "screen": "overview",
  "as_of": "2026-11-05",
  "generated_at": "2026-11-06T04:50:00Z",
  "cohort": { "status": "ok", "denominator": "cohort" },
  "privacy": { "cohort_floor": 20, "cell_floor": 5 },
  "sections": {
    "composition": {
      "status": "ok",
      "buckets": [{ "key": "major", "share_pct": 18, "suppressed": false }],
      "unpublished_pct": 2
    }
  }
}
```

There are six screens: `overview`, `geography`, `qualifications`, `aircraft`, `score` and `intent`. Each takes the same filters a member's screen takes, at most three at a time. The [API reference](https://developers.mypilotindex.com/api-reference/introduction.md) lists them. An unknown filter, a repeated one, or a value outside the vocabulary answers `400 invalid_request`, and a name outside the six screens answers `404 not_found`.

## How the figures are protected

The server applies the floors, so your code never has to:

* A cohort under the floor answers `status: "insufficient"` and no section.
* A cell under its floor is suppressed, and the share it held shows in `unpublished_pct`.
* A filter that would leave too few pilots is dropped, and the answer says so in `filters.broadened`.

No answer carries a count of pilots. A cohort size is a band, never a number. A publication that has never run answers only `schema_version`, `screen`, `generated_at` and `cohort`, with status `not_ready`.

## Show a pilot their position

```bash theme={null}
curl https://{api-host}/v1/partner/grants/{grant_id}/workforce-position \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

```json theme={null}
{
  "schema_version": 1,
  "as_of": "2026-11-05",
  "generated_at": "2026-11-06T09:12:00Z",
  "privacy": { "cohort_floor": 20, "cell_floor": 5 },
  "cohort": { "status": "ok", "level": 2, "n_band": "250_499" },
  "metrics": {
    "total_hours": { "status": "ok", "percentile": 62, "cohort_median": 1180 },
    "score": { "status": "ok", "percentile": 71, "cohort_median": 431.5 },
    "type_rating_count": { "status": "missing" }
  }
}
```

The six metrics are `total_hours`, `pic_hours`, `score`, `type_rating_count`, `years_experience` and `international_hours`. Each has a `status` of `ok`, `missing` or `insufficient`, and `percentile` and `cohort_median` appear only with `ok`.

`cohort.level` says which rung of the cohort answered, from 1, the most specific, to 4, everyone. The answer names the pilot nowhere.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.