---
title: "Evaluate a supplied profile panel against one eligibility snapshot"
method: POST
path: "/v1/eligibility/cohort/evaluate"
tags: ["Data & Analytics"]
---

# Evaluate a supplied profile panel against one eligibility snapshot

`POST /v1/eligibility/cohort/evaluate`

## Request

- Base URL: `https://api.rateapi.dev`
- URL: `https://api.rateapi.dev/v1/eligibility/cohort/evaluate`
- Auth: API key in header `X-API-Key`

Evaluates up to 10 caller-supplied named profiles against one pinned exhaustive graph, one union product query, and one proof read. Aggregate counts describe only the supplied panel and must never be extrapolated to a population, audience, approval, or conversion claim. Profile facts and results are private and returned with `Cache-Control: no-store`.

**Authentication required**: Pass your API key in the `X-API-Key` header.

## Request body

- object
  - `profiles` object[], required: Caller-supplied bounded panel evaluated without population extrapolation.
    - `name` string, required: Unique neutral profile label; do not put direct identifiers here.
    - `person` Person, required (unresolved $ref)
  - `product` Product, required (unresolved $ref)
  - `limit` integer: Maximum aggregate institutions and deduplicated exact offers returned.

## Response `200`

Per-profile results plus deduplicated bounded summary for the supplied panel.

- object
  - `product` Product, required (unresolved $ref)
  - `profiles` object[], required: Per-profile graph-first results for this supplied panel only.
  - `aggregate` object, required: Deduplicated institutions and exact offers observed across this supplied panel.
  - `methodology` object, required: Scope, denominator, deduplication, and non-extrapolation rules for interpreting the aggregate.
  - `snapshot` object, required: Shared graph generation, publication identities, and rate-read boundary used for every profile.
  - `semantics` string, required: Positive-evidence and unknown-safe cohort semantics.
  - `disclosure` string, required: Required statement that this supplied panel is not a population, approval, or conversion estimate.

## Other responses

- `400`: The request was malformed — a missing required field, an unparseable body, or a parameter outside its allowed range. The `error` field names what was wrong; retrying the identical request will fail identically.
- `401`: No API key, or a key that is unknown or disabled. Send it in the `X-API-Key` header. Free keys are issued instantly by POST /keys with an email address. The response carries `WWW-Authenticate` pointing at this host's protected-resource metadata, and the `RateLimit-*` headers describing the Free-tier budget a key issued now would carry (scope `anonymous`) — a rejected request spends none of it, so `Remaining` equals `Limit`.
- `402`: The key is valid, but RateAPI Routes is available only on Enterprise. The response includes `required_plan`, `upgrade_url`, and a `Link` header with `rel="upgrade"`; the rejected request does not consume quota.
- `429`: Quota exhausted for the current window. `Retry-After` gives the seconds to wait; `upgradeInfo` explains how to lift the cap. Retrying before the reset will fail again and still counts as a request.
- `503`: A required serving dependency is temporarily unavailable. This is not a negative eligibility or product decision; retry with backoff or continue using confirmed direct fields on deterministic endpoints.

---

[API](https://skmtc.dev/rateapi/apis/rate-api.md) · [All operations](https://skmtc.dev/rateapi/apis/rate-api/llms.txt) · [OpenAPI document](https://skmtc.dev/rateapi/apis/rate-api/revisions/06a6db76995f?raw)