Grants

Read the pilot against his cohort

Where the pilot of a grant that holds insights.position stands: his percentile and the cohort’s median on six metrics, against the most specific cohort that clears the floor (his country, role and hours band, then wider). It is the answer the pilot reads himself, with the same floors. missing means he never recorded the metric, and insufficient that too few of the cohort did. A publication that has never run answers only schema_version, generated_at and cohort, with status not_ready. A grant that is revoked, unknown or another partner’s answers 404 not_found; a grant, or a token, without insights.position is 403 scope_missing. 403 without a reason is a pilot who has no standing to read the Workforce yet, such as one who has not finished onboarding.

GET

partner

grants

{grant_id}

workforce-position

Read the pilot against his cohort

curl --request GET \
  --url https://{devApiHost}/v1/partner/grants/{grant_id}/workforce-position \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://{devApiHost}/v1/partner/grants/{grant_id}/workforce-position', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://{devApiHost}/v1/partner/grants/{grant_id}/workforce-position"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

{
  "schema_version": 1,
  "as_of": "2026-11-07",
  "generated_at": "2026-11-07T12:00:00Z",
  "privacy": {
    "cell_floor": 5,
    "cohort_floor": 20
  },
  "cohort": {
    "status": "ok",
    "keys": {
      "country": "BR",
      "role": "first_officer"
    },
    "level": 2,
    "n_band": "100_249"
  },
  "metrics": {
    "total_hours": {
      "status": "ok",
      "percentile": 65,
      "cohort_median": 1500
    },
    "international_hours": {
      "status": "missing"
    }
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "correlation_id": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "correlation_id": "<string>",
    "reason": "scope_missing"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "correlation_id": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "correlation_id": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "correlation_id": "<string>",
    "reason": "rate_limited"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "correlation_id": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "correlation_id": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "correlation_id": "<string>",
    "reason": "<string>"
  }
}

Authorizations

Authorization

string

header

required

OAuth 2.0 client credentials. Request a token from the token endpoint of the identity provider's domain (https://{cognito-domain}/oauth2/token, with HTTP Basic client authentication) and send it as a Bearer token. Production uses auth.mypilotindex.com. The sandbox uses the dev environment's Cognito domain, which is given to the partner with its sandbox credential. A token carries only the scopes the partner was approved for.

Path Parameters

grant_id

string<uuid>

required

Response

The pilot's position.

One pilot's six metrics against his cohort. It names him nowhere.

schema_version

integer

required

generated_at

string<date-time>

required

cohort

object

required

Show child attributes

as_of

string<date> | null

privacy

object

The floors the answer was measured against.

Show child attributes

metrics

object

total_hours, pic_hours, score, type_rating_count, years_experience and international_hours. percentile and cohort_median appear only with status ok.

Show child attributes

⌘I

Read the pilot against his cohort

curl --request GET \
  --url https://{devApiHost}/v1/partner/grants/{grant_id}/workforce-position \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://{devApiHost}/v1/partner/grants/{grant_id}/workforce-position', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://{devApiHost}/v1/partner/grants/{grant_id}/workforce-position"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

{
  "schema_version": 1,
  "as_of": "2026-11-07",
  "generated_at": "2026-11-07T12:00:00Z",
  "privacy": {
    "cell_floor": 5,
    "cohort_floor": 20
  },
  "cohort": {
    "status": "ok",
    "keys": {
      "country": "BR",
      "role": "first_officer"
    },
    "level": 2,
    "n_band": "100_249"
  },
  "metrics": {
    "total_hours": {
      "status": "ok",
      "percentile": 65,
      "cohort_median": 1500
    },
    "international_hours": {
      "status": "missing"
    }
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "correlation_id": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "correlation_id": "<string>",
    "reason": "scope_missing"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "correlation_id": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "correlation_id": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "correlation_id": "<string>",
    "reason": "rate_limited"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "correlation_id": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "correlation_id": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "correlation_id": "<string>",
    "reason": "<string>"
  }
}

Overview

Grants

Jobs

Publishing

Insights

Certificates

Webhooks

Read the pilot against his cohort

Authorizations

Path Parameters

Response