Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: 'superagnt SEO: Keywords API'
description: Unified API for social media data. Access LinkedIn, YouTube, TikTok, X, Instagram, Reddit, and Facebook through a single API key.
version: 1.0.0
contact:
name: superagnt
url: https://superagnt.com
servers:
- url: https://api.superagnt.com
description: superagnt API
security:
- ApiKeyAuth: []
tags:
- name: 'SEO: Keywords'
description: 'Keyword research: ideas, volume, difficulty, intent.'
paths:
/v1/data/seo/keyword-ideas:
post:
operationId: keyword_ideas
summary: Keyword ideas from seed keywords
x-agnt-permission: act
description: Expands up to 200 seed keywords into related keyword ideas, each with search volume, CPC, competition and keyword difficulty (difficulty is at keyword_properties.keyword_difficulty in each row; volume and CPC at keyword_info). Ideas come from category-level expansion, so sorting by search volume surfaces unrelated head terms; the default order is relevance, keep it for topical work and filter instead. Cost scales with rows returned, so keep `limit` at the default 100 unless the task genuinely needs more (hard cap 1000).
tags:
- 'SEO: Keywords'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- keywords
properties:
keywords:
type: array
items:
type: string
maxItems: 200
description: Seed keywords to expand (1-200).
location_code:
type: integer
description: Geo target as a location code. Default 2840 (United States).
default: 2840
language_code:
type: string
description: Two-letter language code. Default 'en'.
default: en
limit:
type: integer
minimum: 1
maximum: 1000
default: 100
description: Max keyword ideas to return. Default 100. Cost scales with rows, so raise only when needed.
offset:
type: integer
minimum: 0
description: Pagination offset.
filters:
type: array
items: {}
description: 'Optional filter expression as [field, operator, value] triples joined by ''and''/''or''. Operators: =, <>, <, <=, >, >=, in, not_in, like, not_like (use %% wildcards with like). Recipes: [["keyword_info.search_volume",">",100]] · keep only on-topic ideas: [["keyword","like","%deliverability%"]] · combine: [["keyword_info.search_volume",">",100],"and",["keyword_properties.keyword_difficulty","<",40]].'
order_by:
type: array
items:
type: string
description: Sort rules, e.g. ["keyword_info.search_volume,desc"].
example:
keywords:
- email warmup
- cold email deliverability
limit: 100
responses:
'200':
description: Keyword ideas with volume, CPC, competition and difficulty in `result[0].items`.
content:
application/json:
schema:
type: object
'400':
description: Bad request or upstream task error.
'401':
description: Unauthorized.
'429':
description: Too many requests.
5XX:
description: Upstream error.
security:
- ApiKeyAuth: []
/v1/data/seo/keyword-overview:
post:
operationId: keyword_overview
summary: Metrics for specific keywords
x-agnt-permission: act
description: 'Returns full metrics for the exact keywords you pass: search volume, CPC and competition (keyword_info), keyword difficulty (keyword_properties.keyword_difficulty), trend history and SERP characteristics. Use this when you already know the keywords and need their numbers; use keyword_ideas when you need to discover keywords.'
tags:
- 'SEO: Keywords'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- keywords
properties:
keywords:
type: array
items:
type: string
maxItems: 700
description: The exact keywords to look up (1-700). Cost scales with the number of keywords.
location_code:
type: integer
description: Geo target as a location code. Default 2840 (United States).
default: 2840
language_code:
type: string
description: Two-letter language code. Default 'en'.
default: en
example:
keywords:
- crm migration
- hubspot alternative
responses:
'200':
description: Per-keyword metrics in `result[0].items`.
content:
application/json:
schema:
type: object
'400':
description: Bad request or upstream task error.
'401':
description: Unauthorized.
'429':
description: Too many requests.
5XX:
description: Upstream error.
security:
- ApiKeyAuth: []
/v1/data/seo/search-intent:
post:
operationId: search_intent
summary: Classify keyword search intent
x-agnt-permission: act
description: 'Classifies each keyword''s search intent (informational, navigational, commercial, transactional) with a probability score. Use it to split a keyword list into content types: informational keywords get articles, transactional ones get landing pages.'
tags:
- 'SEO: Keywords'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- keywords
properties:
keywords:
type: array
items:
type: string
maxItems: 1000
description: Keywords to classify (1-1000). Cost scales with the number of keywords.
language_code:
type: string
description: Two-letter language code. Default 'en'.
default: en
example:
keywords:
- what is a crm
- buy crm software
- salesforce login
responses:
'200':
description: Per-keyword intent labels and probabilities in `result[0].items`.
content:
application/json:
schema:
type: object
'400':
description: Bad request or upstream task error.
'401':
description: Unauthorized.
'429':
description: Too many requests.
5XX:
description: Upstream error.
security:
- ApiKeyAuth: []
/v1/data/seo/ranked-keywords:
post:
operationId: ranked_keywords
summary: Keywords a domain ranks for
x-agnt-permission: act
description: 'Returns the keywords a domain (or a specific page) currently ranks for in Google, with position, search volume, and the ranked URL. The core competitor research call: point it at any domain to see its organic footprint. Cost scales with rows, so keep `limit` at the default 100 and use `filters` (e.g. position <= 20) instead of pulling thousands of rows. Row shape: items[].keyword_data.keyword_info.search_volume, items[].keyword_data.keyword_properties.keyword_difficulty, items[].ranked_serp_element.serp_item.rank_absolute.'
tags:
- 'SEO: Keywords'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- target
properties:
target:
type: string
description: Domain (e.g. 'example.com', no protocol) or full page URL to analyze.
location_code:
type: integer
description: Geo target as a location code. Default 2840 (United States).
default: 2840
language_code:
type: string
description: Two-letter language code. Default 'en'.
default: en
limit:
type: integer
minimum: 1
maximum: 1000
default: 100
description: Max keywords to return. Default 100. Cost scales with rows.
offset:
type: integer
minimum: 0
description: Pagination offset.
filters:
type: array
items: {}
description: Optional filter expression, e.g. [["ranked_serp_element.serp_item.rank_absolute", "<=", 20]].
order_by:
type: array
items:
type: string
description: Sort rules, e.g. ["keyword_data.keyword_info.search_volume,desc"].
example:
target: close.com
limit: 100
order_by:
- keyword_data.keyword_info.search_volume,desc
responses:
'200':
description: Ranked keywords with positions and volumes in `result[0].items`.
content:
application/json:
schema:
type: object
'400':
description: Bad request or upstream task error.
'401':
description: Unauthorized.
'429':
description: Too many requests.
5XX:
description: Upstream error.
security:
- ApiKeyAuth: []
/v1/data/seo/keyword-gap:
post:
operationId: keyword_gap
summary: Keyword gap between two domains
x-agnt-permission: act
description: 'Compares two domains'' organic rankings keyword by keyword. Each row carries keyword_data plus first_domain_serp_element (target1''s ranking) and second_domain_serp_element (target2''s) with rank_absolute, rank_group and the ranked URL. The classic gap query is: competitor ranks well, you don''t — filters: [["first_domain_serp_element.rank_absolute",">",20],"and",["second_domain_serp_element.rank_absolute","<=",10]] with target1 = you, target2 = the competitor (a missing element means that domain does not rank at all). Cost scales with rows; the default 100 is enough for most gap analyses.'
tags:
- 'SEO: Keywords'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- target1
- target2
properties:
target1:
type: string
description: First domain (e.g. your domain), no protocol.
target2:
type: string
description: Second domain (e.g. a competitor), no protocol.
location_code:
type: integer
description: Geo target as a location code. Default 2840 (United States).
default: 2840
language_code:
type: string
description: Two-letter language code. Default 'en'.
default: en
limit:
type: integer
minimum: 1
maximum: 1000
default: 100
description: Max intersecting keywords to return. Default 100.
offset:
type: integer
minimum: 0
description: Pagination offset.
filters:
type: array
items: {}
description: 'Optional filter expression as [field, operator, value] triples joined by ''and''/''or''. Operators: =, <>, <, <=, >, >=, in, not_in, like, not_like. Recipe (their wins, your gaps): [["first_domain_serp_element.rank_absolute",">",20],"and",["second_domain_serp_element.rank_absolute","<=",10]].'
order_by:
type: array
items:
type: string
description: Sort rules.
example:
target1: yourapp.com
target2: competitor.com
limit: 100
responses:
'200':
description: Keywords both domains rank for, with each domain's position, in `result[0].items`.
content:
application/json:
schema:
type: object
'400':
description: Bad request or upstream task error.
'401':
description: Unauthorized.
'429':
description: Too many requests.
5XX:
description: Upstream error.
security:
- ApiKeyAuth: []
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Authorization
description: 'Bearer token. Pass your agntdata API key as: Authorization: Bearer agnt_live_...'