# search_projects > Find projects by a description of the idea, by similarity to one or more projects already on hand, or by conditions on their measured profile… Find projects by a description of the idea, by similarity to one or more projects already on hand, or by conditions on their measured profile — quality axes, scale band, growth direction, country, site type — in any combination. Every project in the corpus is a site where revenue has been observed; how much a site earns and what it charges is not part of this corpus. Returns cards: id, short description, site type, quality index, scale band, growth, main country and niche. The domain appears only on projects your organization has revealed; reveal_project turns a card into a domain. With text or seed projects, the results are the projects closest in meaning, the seeds themselves left out; sorting by index, scale or growth then orders the closest ones only, as many as relevance_pool in capabilities. Costs the base price plus the first-seen price for every project shown to your organization for the first time this period, and each such project spends one unit of coverage; without limit a call returns as many rows as list_max in capabilities allows. Call with estimate: true to see the price and get a quote_token first. Use it when your user describes a kind of site or the niche is already known; for a market question start with search_cohorts, and for a domain your user already has use lookup_domain. ## Request ```text POST https://api.megido.io/v1/tools/search_projects ``` 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 idea to look for", "type": "string", "minLength": 1 }, "seed": { "description": "Projects the results should resemble; they are left out of the results; seed and anti_seed together are refused above list_max in capabilities", "type": "array", "items": { "type": "string", "pattern": "^p_[a-z2-7]{16}$", "description": "Opaque project id as returned by this server to your organization" } }, "anti_seed": { "description": "Projects the results should not resemble; needs text or seed, and must not repeat a seed", "type": "array", "items": { "type": "string", "pattern": "^p_[a-z2-7]{16}$", "description": "Opaque project id as returned by this server to your organization" } }, "filters": { "description": "Conditions on the measured profile", "type": "object", "properties": { "cohort_id": { "description": "Restrict to the core members of this niche; projects on its edge (edge: true in a project card's niches) are left out", "type": "string", "pattern": "^c_[a-z2-7]{16}$" }, "index_min": { "description": "Minimum total quality index", "type": "number", "minimum": 0, "maximum": 100 }, "index_max": { "description": "Maximum total quality index", "type": "number", "minimum": 0, "maximum": 100 }, "liveness_min": { "description": "Minimum liveness axis", "type": "number", "minimum": 0, "maximum": 100 }, "demand_quality_min": { "description": "Minimum demand quality axis", "type": "number", "minimum": 0, "maximum": 100 }, "acquisition_reproducibility_min": { "description": "Minimum acquisition reproducibility axis", "type": "number", "minimum": 0, "maximum": 100 }, "scale_band": { "description": "Allowed scale bands", "maxItems": 6, "type": "array", "items": { "type": "string", "enum": [ "lt_500", "b500_3k", "b3k_15k", "b15k_75k", "b75k_1m", "gte_1m" ] }, "uniqueItems": true }, "growth": { "description": "Allowed growth bands", "maxItems": 6, "type": "array", "items": { "type": "string", "enum": [ "collapsing", "declining_fast", "declining", "flat", "growing", "growing_fast" ] }, "uniqueItems": true }, "country": { "description": "Allowed main countries", "maxItems": 249, "type": "array", "items": { "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": "ISO 3166-1 alpha-2 country code" }, "uniqueItems": true }, "type": { "type": "string", "enum": [ "product", "content" ], "description": "Site type" } }, "additionalProperties": false }, "sort": { "description": "relevance (closeness to text and seed; the default with them, and it requires them), index (total quality index; the default without text or seed), scale (monthly visits) or growth (last-month change); with text or seed, index, scale and growth order the relevance_pool closest projects", "type": "string", "enum": [ "relevance", "index", "scale", "growth" ] }, "exclude": { "description": "Projects already seen, to leave out; refused above cursor_depth in capabilities", "type": "array", "items": { "type": "string", "pattern": "^p_[a-z2-7]{16}$", "description": "Opaque project id as returned by this server to your organization" } }, "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: `SearchProjectsAnswer` | | 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`, `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.