# get_keywords > Return the search demand behind a project: the branded and non-branded split of its organic search traffic, the top organic queries with their shares… Return the search demand behind a project: the branded and non-branded split of its organic search traffic, the top organic queries with their shares and month-over-month change, and, with include_paid, the top paid queries. Individual queries identify a site in any search tool, so before a reveal only the split is returned. After a reveal, each query's month-over-month change is an exact number even with precision: band. Costs the base price plus the keywords price for every project whose keywords your organization does not already hold, and with precision: exact a surcharge for every revealed project on every call; a project without search data comes back with profile null and is charged neither the part nor the exact surcharge. Ask in bands first, and for exact values only when your user needs exact numbers. ## Request ```text POST https://api.megido.io/v1/tools/get_keywords ``` 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": { "refs": { "description": "Projects to describe; refused above batch.get_keywords in capabilities; required unless quote_token is given", "minItems": 1, "type": "array", "items": { "type": "string", "pattern": "^p_[a-z2-7]{16}$", "description": "Opaque project id as returned by this server to your organization" } }, "precision": { "type": "string", "enum": [ "band", "exact" ], "description": "band (default) or exact; exact applies only to revealed projects, adds a surcharge for each of them, and is otherwise ignored with a note" }, "include_paid": { "description": "Include top paid queries (revealed projects only)", "type": "boolean" }, "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": [ "refs" ] } ], "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: `GetKeywordsAnswer` | | 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` | | 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` | 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.