---
title: "run_keyword_research"
method: POST
path: "/api/v1/run_keyword_research"
---

# run_keyword_research

`POST /api/v1/run_keyword_research`

## Request

- Base URL: `https://app.miraqo.io`
- URL: `https://app.miraqo.io/api/v1/run_keyword_research`
- Auth: HTTP bearer

Avvia una ricerca keyword e ritorna un job_id: richiama lo stesso tool passando job_id per avere i risultati (volume, CPC, intent, difficulty = indice di competizione Google Ads 0-100, NON difficoltà SEO), di solito pronti entro un paio di minuti. mode: related (da una seed), list (volumi di una lista), domain (keyword di un dominio), gap (keyword del competitor non coperte dal dominio). Con project_id marca le keyword già tracciate. Il ritiro con job_id non consuma quota. AZIONE A PAGAMENTO: consuma 1 unità della quota mensile del piano e 1 azione MCP (tetto dedicato). Usa get_usage per i crediti residui.

## Request body

- object
  - `mode` 'related' | 'list' | 'domain' | 'gap'
  - `job_id` integer: ritira una ricerca già avviata
  - `seed` string: keyword di partenza (mode=related)
  - `keywords` string[]: lista keyword (mode=list)
  - `domain` string: dominio (mode=domain/gap)
  - `competitor` string: dominio competitor (mode=gap)
  - `location_code` integer: default 2380 (Italia)
  - `language_code` string: default 'it'
  - `project_id` integer
  - `organization_id` integer

## Response `200`

ok=true, risultato in data

## Other responses

- `400`: ok=false, messaggio in error

---

[API](https://skmtc.dev/miraqo/apis/miraqo-api.md) · [All operations](https://skmtc.dev/miraqo/apis/miraqo-api/llms.txt) · [OpenAPI document](https://skmtc.dev/miraqo/apis/miraqo-api/revisions/6c922bc12f0e?raw)