---
title: "Keyword Metrics"
method: POST
path: "/tools/keyword-metrics/runs"
tags: ["SEO"]
---

# Keyword Metrics

`POST /tools/keyword-metrics/runs`

## Request

- Base URL: `https://seogeoaeo.ai/api/v1`
- URL: `https://seogeoaeo.ai/api/v1/tools/keyword-metrics/runs`
- Auth: HTTP bearer

Rank a keyword list you already have by search volume, difficulty and ad cost, so you know which to write about or bid on first. Paste a list of keywords and get each one's monthly Google searches, difficulty, cost per click and yearly trend, sorted into easy wins, blog topics and keywords worth bidding on. Costs 33 credits per run. Docs: https://seogeoaeo.ai/tools/keyword-metrics

## Headers

- `Idempotency-Key` string: Reuse on retries so the same run is returned instead of charged again. A key only matches a run of the same tool and input, and only while that run is among the workspace's latest 1,000.

## Request body

- object
  - `input` object, required
    - `keywords` string, required: Newline-separated keyword list.
    - `market` 'us' | 'gb' | 'ca' | 'au' | 'ie' | 'in' | 'sg' | 'nz' | 'za' | 'de' | 'fr' | 'es' | 'it' | 'nl' | 'se' | 'pl' | 'br' | 'mx' | 'jp' | 'ae': Market code for localized results.
  - `idempotencyKey` string: Reuse on retries so the same run is returned instead of charged again. A key only matches a run of the same tool and input, and only while that run is among the workspace's latest 1,000.
  - `maxCredits` integer: Refuse the run with max_credits_exceeded if it costs more than this.

## Response `200`

Finished run.

- object
  - `run` Run, required
    - `id` string
    - `toolId` string
    - `slug` string
    - `toolVersion` string
    - `status` 'succeeded' | 'failed'
    - `creditsCharged` integer
    - `priceVersion` string
    - `input` object
    - `result` unknown
    - `improvementTips` ImprovementTips, nullable: What to change to improve the result. Null when the run failed or its result is no longer available.
      - `status` 'changes' | 'clean' | 'incomplete', required: incomplete when any part of the analysis could not run, changes when there are tips, clean when the tool checked everything and found nothing to change.
      - `summary` string, required: Plain-text checklist of every tip, ordered by priority.
      - `tips` ImprovementTip[], required
        - `id` string, required: Names one kind of change and stays the same across runs, so a fixed tip is recognized by its absence.
        - `priority` 'high' | 'medium' | 'low', required
        - `title` string, required
        - `action` string, required: The change to make.
        - `why` string, required
        - `detail` string, required: What the tool observed.
        - `affected` string[], required: URLs, headers, or items the change applies to.
        - `fixIn` 'dns' | 'external': Set when the change is made outside the site's code: in DNS, or in another service.
      - `unchecked` object[], required: Parts of the analysis that could not run. While not empty, the result cannot show that the site is clean.
        - `id` string, required
        - `title` string, required
        - `detail` string, required: What went wrong.
        - `action` string, required: What to do before trusting the result.
      - `rerunVerifies` boolean, required: True when running the tool again with the same input shows whether the changes worked. False when the tips come from the input, so the same input returns them again.
      - `verify` string, required: How to confirm the changes worked.
    - `errorClass` string, nullable
    - `errorMessage` string, nullable
    - `createdAt` string, date-time
    - `startedAt` string, date-time, nullable
    - `finishedAt` string, date-time, nullable

## Other responses

- `400`: Error envelope.
- `401`: Error envelope.
- `402`: Error envelope.
- `404`: Error envelope.
- `409`: Error envelope.
- `413`: Error envelope.
- `429`: Error envelope.
- `502`: Error envelope.
- `503`: Error envelope.

---

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