Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: 'superagnt SEO: Competitors 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: Competitors'
description: What competitor domains rank for and where you overlap.
paths:
/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: Competitors'
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: Competitors'
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: []
/v1/data/seo/competitors:
post:
operationId: competitors
summary: Find a domain's organic competitors
x-agnt-permission: act
description: 'Returns the domains that compete with the target in organic search, ranked by keyword overlap (the `intersections` field), with visibility and traffic estimates for each. Note: the first row is the target itself, and generic high-overlap mega-domains (youtube.com, linkedin.com) dominate the default output — skip the self row and filter, e.g. filters: [["intersections",">",50]], or sort with order_by: ["metrics.organic.count,desc"] and judge overlap yourself. Feed the survivors into keyword_gap or backlink_gap.'
tags:
- 'SEO: Competitors'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- target
properties:
target:
type: string
description: Domain to find competitors for, 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 competitor domains to return. Default 100.
filters:
type: array
items: {}
description: 'Optional filter expression as [field, operator, value] triples. Recipe: [["intersections",">",50]] keeps only domains sharing 50+ keywords with the target.'
order_by:
type: array
items:
type: string
description: Sort rules, e.g. ["intersections,desc"].
example:
target: close.com
limit: 50
responses:
'200':
description: Competitor domains with overlap and visibility 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/domain-overview:
post:
operationId: domain_overview
summary: Domain rank and traffic overview
x-agnt-permission: act
description: 'One-call summary of a domain''s organic footprint: domain rank, number of ranking keywords, estimated organic traffic and its value, split by position buckets. The cheap first call when qualifying a domain: run this before deciding whether a deeper ranked_keywords or backlinks pull is worth it.'
tags:
- 'SEO: Competitors'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- target
properties:
target:
type: string
description: Domain to summarize, 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
example:
target: close.com
responses:
'200':
description: Domain metrics summary 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/backlink-gap:
post:
operationId: backlink_gap
summary: Domains linking to competitors but not you
x-agnt-permission: act
description: 'Finds domains that link to one or more competitor targets but NOT to the excluded target (you). The output is a ready-made link-building prospect list; chain it with an email-finder tool to turn rows into outreach. Response shape: each row''s referring domain lives at items[].domain_intersection["1"], ["2"], ... keyed by the 1-based index of your `targets` array, with that referring domain''s own authority score in `rank` (0-1000ish, higher is stronger; this is the referring domain''s rank, a different metric from the target-domain rank in backlinks_summary). Default sort is rank descending. When ranking prospects, check referring_domains and backlinks together — a huge backlink count with few referring domains usually means sitewide boilerplate links, not authority.'
tags:
- 'SEO: Competitors'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- targets
properties:
targets:
type: array
items:
type: string
minItems: 1
maxItems: 20
description: Competitor domains whose backlink sources to intersect (1-20).
exclude_targets:
type: array
items:
type: string
maxItems: 10
description: Domains the referring sites must NOT already link to. Put your own domain here.
limit:
type: integer
minimum: 1
maximum: 1000
default: 100
description: Max referring domains to return. Default 100.
offset:
type: integer
minimum: 0
description: Pagination offset.
filters:
type: array
items: {}
description: Optional filter expression, e.g. minimum domain rank.
order_by:
type: array
items:
type: string
description: Sort rules, e.g. ["1.rank,desc"].
example:
targets:
- competitor-a.com
- competitor-b.com
exclude_targets:
- yourapp.com
limit: 100
responses:
'200':
description: Referring domains that link to the targets, 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_...'