> ## 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

> Leia a força de trabalho de pilotos como um mercado e mostre a um piloto onde ele está entre os colegas.

Os Insights têm duas leituras. Um parceiro com `insights.read` lê o Workforce: como os pilotos do MyPilotIndex se apresentam como mercado, em agregados. Um app de piloto com um grant que tem `insights.position` lê onde um piloto está em relação à coorte dele.

## Leia o 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
    }
  }
}
```

São seis telas: `overview`, `geography`, `qualifications`, `aircraft`, `score` e `intent`. Cada uma aceita os mesmos filtros da tela de um membro, no máximo três por vez. A [referência da API](https://developers.mypilotindex.com/pt-br/api-reference/introduction.md) lista esses filtros. Um filtro desconhecido ou repetido, ou um valor fora do vocabulário, responde `400 invalid_request`, e um nome fora das seis telas responde `404 not_found`.

## Como os números são protegidos

O servidor aplica os pisos, então o seu código nunca precisa fazer isso:

* Uma coorte abaixo do piso responde `status: "insufficient"` e nenhuma seção.
* Uma célula abaixo do próprio piso é suprimida, e a fatia que ela tinha aparece em `unpublished_pct`.
* Um filtro que deixaria poucos pilotos é removido, e a resposta informa isso em `filters.broadened`.

Nenhuma resposta traz uma contagem de pilotos. O tamanho de uma coorte é uma faixa, nunca um número. Uma publicação que nunca rodou responde só `schema_version`, `screen`, `generated_at` e `cohort`, com o status `not_ready`.

## Mostre a um piloto a posição dele

```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" }
  }
}
```

As seis métricas são `total_hours`, `pic_hours`, `score`, `type_rating_count`, `years_experience` e `international_hours`. Cada uma tem um `status` `ok`, `missing` ou `insufficient`, e `percentile` e `cohort_median` só aparecem com `ok`.

`cohort.level` diz qual degrau da coorte respondeu, de 1, o mais específico, a 4, todos. A resposta não nomeia o piloto em lugar nenhum.


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