# search_cohorts > Find market niches either by describing them in words or by conditions on the niche itself: size, level in the hierarchy, median quality index, share… Find market niches either by describing them in words or by conditions on the niche itself: size, level in the hierarchy, median quality index, share of growing members (members whose visits grew by more than 10% over the last month), leading country. Every project underneath these niches is a site where revenue has been observed, so a niche here is a market rather than a topic. Returns niche ids with a gloss, the number of member projects and a quality summary — never their member sites. With text, the results are the niches closest in meaning; sorting by size, index or growth then orders the closest ones only, as many as relevance_pool_cohorts in capabilities. Costs the base price plus the first-seen price for every niche shown to your organization for the first time this period, and each such niche spends one unit of coverage; call with estimate: true to see the price and get a quote_token first. This is the cheapest way into a market: use it before searching for projects when the user cannot yet name a single site in the space. ## Request ```text POST https://api.megido.io/v1/tools/search_cohorts ``` 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; {} or no body for none. Its JSON Schema: ```json { "type": "object", "properties": { "text": { "description": "Free-text description of the market to look for", "type": "string", "minLength": 1 }, "filters": { "description": "Conditions on the niche itself", "type": "object", "properties": { "min_size": { "description": "Minimum number of member projects in the corpus", "type": "integer", "minimum": 0, "maximum": 2147483647 }, "max_size": { "description": "Maximum number of member projects in the corpus", "type": "integer", "exclusiveMinimum": 0, "maximum": 2147483647 }, "level": { "description": "Level in the niche hierarchy: 1 holds the narrowest niches, each higher level groups the level below; see capabilities for the levels", "type": "integer", "minimum": -2147483647, "maximum": 2147483647 }, "index_min": { "description": "Minimum median quality index of members, 0..100", "type": "number", "minimum": 0, "maximum": 100 }, "growing_share_min": { "description": "Minimum share of members whose visits grew by more than 10% over the last month, percent", "type": "number", "minimum": 0, "maximum": 100 }, "country": { "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "YE", "YT", "ZA", "ZM", "ZW" ], "description": "Leading country of the niche" } }, "additionalProperties": false }, "sort": { "description": "relevance (closeness to text; the default with text, and it requires text), size (the default without text), index (median quality index) or growth (share of growing members); with text, size, index and growth order the relevance_pool_cohorts closest niches. Index and growth are shares of members, so without filters.min_size niches of a few members come first", "type": "string", "enum": [ "relevance", "size", "index", "growth" ] }, "limit": { "description": "Rows to return; defaults to list_max in capabilities and is refused above it", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "cursor": { "description": "Continue a previous page: repeat the same query parameters (limit may change) and pass the cursor it returned", "type": "string", "minLength": 1 }, "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, "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: `SearchCohortsAnswer` | | 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` | | 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`, `layer_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.