# get_cohort > Open one niche: its gloss with labeling confidence, size, the distribution of its members over quality index bands, scale bands, growth bands… Open one niche: its gloss with labeling confidence, size, the distribution of its members over quality index bands, scale bands, growth bands, countries and site types in whole percents, its position in the hierarchy — parent, children, neighboring niches — and a stable sample of member projects as cards. Opening the niche itself spends no coverage; every parent, child, neighbor and sample member shown to your organization for the first time this period costs the first-seen price on top of the base price and spends one unit of coverage, so ask only for the parts you need. Use the hierarchy to widen or narrow the market definition instead of searching again. It takes a niche id: to find a niche by words or by conditions use search_cohorts. ## Request ```text POST https://api.megido.io/v1/tools/get_cohort ``` Headers: `Authorization: Bearer `, and with a body `Content-Type: application/json`. `Idempotency-Key` (header, optional): A key of your own for this call, up to 200 characters, such as a UUID, that makes a retry safe: the same key with the same arguments returns the first answer, with meta.replayed: true and without charging again; with other arguments or another tool it is refused. A key is unique within your organization; values that start with task: are reserved. The tool's arguments. Its JSON Schema: ```json { "type": "object", "properties": { "cohort_id": { "description": "Niche to open; required unless quote_token is given", "type": "string", "pattern": "^c_[a-z2-7]{16}$" }, "parts": { "description": "Which sections to include; all when omitted", "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "distributions", "sample", "hierarchy" ] }, "uniqueItems": true }, "sample_limit": { "description": "Members in the sample; defaults to the limit named sample in capabilities and is refused above it", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "sample_sort": { "description": "distance (default): the most typical member and the core members nearest to it; index: the core members with the highest quality index", "type": "string", "enum": [ "distance", "index" ] }, "estimate": { "description": "When true, run the query but return only its composition, price and a quote_token instead of data", "type": "boolean" }, "quote_token": { "description": "Execute a previous estimate: pass the quote_token instead of the query parameters", "type": "string", "minLength": 1 } }, "additionalProperties": false, "anyOf": [ { "required": [ "quote_token" ] }, { "required": [ "cohort_id" ] } ], "not": { "properties": { "estimate": { "const": true } }, "required": [ "estimate", "quote_token" ] } } ``` ## Answers | Status | Answer | |---|---| | 200 | The tool's answer, or with estimate: true its estimate, whose data is a Quote holding quote_token: `GetCohortAnswer` | | 400 | The request cannot be served as sent: `bad_request`, `invalid_params`, `limit_exceeded`, `invalid_quote_token`, `unknown_filter_value` | | 401 | No key, or a key the API does not take: `unauthorised` | | 402 | Not enough credits: `insufficient_balance`, `quota_exhausted` | | 403 | Not allowed for your organization or your key: `org_suspended`, `coverage_exceeded` | | 409 | In conflict with the state of a quote, the corpus or a task: `quote_expired`, `quote_spent`, `quote_outdated`, `confirmation_required`, `corpus_updated`, `cohort_rebuilt` | | 413 | The body is larger than the API takes: `bad_request` | | 415 | The body is not sent as application/json: `bad_request` | | 429 | Too many calls: `rate_limited` | | 500 | The call failed on Megido's side: `internal_error` | | 503 | Not available just now: `service_unavailable`, `lock_timeout`, `tool_unavailable` | Every error has the body `{"error": {"code": "…", "message": "…"}}` with the details of its code. The OpenAPI document holds every schema: https://api.megido.io/v1/openapi.json.