KosmoKrator

data

Ahrefs Lua API for KosmoKrator Agents

Agent-facing Lua documentation and function reference for the Ahrefs KosmoKrator integration.

Lua Namespace

Agents call this integration through app.integrations.ahrefs.*. Use lua_read_doc("integrations.ahrefs") inside KosmoKrator to discover the same reference at runtime.

Call Lua from the Headless CLI

Use kosmo integrations:lua when a shell script, CI job, cron job, or another coding CLI should run a deterministic Ahrefs workflow without starting an interactive agent session.

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.ahrefs.list_backlinks({target = "example_target", limit = 1, offset = 1, mode = "example_mode"}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("ahrefs"))' --json
kosmo integrations:lua --eval 'print(docs.read("ahrefs.list_backlinks"))' --json

Workflow file

Put repeatable logic in a Lua file, then execute it with JSON output for the calling process.

workflow.lua 
local ahrefs = app.integrations.ahrefs
local result = ahrefs.list_backlinks({target = "example_target", limit = 1, offset = 1, mode = "example_mode"})

dump(result)
Run the workflow 
kosmo integrations:lua workflow.lua --json
kosmo integrations:lua workflow.lua --force --json
Namespace note. integrations:lua exposes app.integrations.ahrefs, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.ahrefs.default.* or app.integrations.ahrefs.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need Ahrefs, use the narrower mcp:lua command.

MCP Lua command 
# Use mcp:lua for MCP-only scripts; use integrations:lua for this integration namespace.
kosmo mcp:lua --eval 'dump(mcp.servers())' --json

Agent-Facing Lua Docs

This is the rendered version of the full Lua documentation exposed to agents when they inspect the integration namespace.

Ahrefs Lua Reference

Namespace: ahrefs

Ahrefs tools target API v3. Configure an Ahrefs API key; the integration sends it as Authorization: Bearer <api_key>.

Site Explorer

Use Site Explorer tools for backlink, organic, paid, and overview reports. Most new tools accept a params object so agents can pass Ahrefs API fields such as target, date, mode, country, limit, offset, select, and where without the integration hiding upstream options.

local metrics = app.integrations.ahrefs.get_metrics({
  params = {
    target = "example.test",
    date = "2026-05-06",
    mode = "domain",
    country = "us",
  },
})

local dr = app.integrations.ahrefs.get_domain_rating({
  params = { target = "example.test", date = "2026-05-06" },
})

local backlinks = app.integrations.ahrefs.list_backlinks({
  target = "example.test",
  mode = "domain",
  limit = 25,
})

local broken = app.integrations.ahrefs.list_broken_backlinks({
  params = { target = "example.test", mode = "domain", limit = 25 },
})

local competitors = app.integrations.ahrefs.list_organic_competitors({
  params = { target = "example.test", mode = "domain", date = "2026-05-06", country = "us" },
})

Additional Site Explorer tools:

  • list_referring_domains({ target, limit?, offset?, mode? })
  • list_organic_keywords({ target, limit?, offset?, mode? })
  • list_pages({ target, limit?, offset?, mode? })
  • list_paid_pages({ params })
  • list_anchors({ target, limit?, offset? })
  • list_linked_domains({ params })
  • get_backlinks_stats({ params })

Subscription

local usage = app.integrations.ahrefs.get_limits_and_usage({})

This replaces the old current-user helper. Ahrefs API v3 documents subscription limits and usage, not a /users/me profile endpoint.

Generic API

Use api_get for Ahrefs API v3 endpoints without dedicated wrappers:

local result = app.integrations.ahrefs.api_get({
  path = "/v3/site-explorer/metrics-by-country",
  params = {
    target = "example.test",
    date = "2026-05-06",
    mode = "domain",
  },
})
Raw agent markdown 
# Ahrefs Lua Reference

Namespace: `ahrefs`

Ahrefs tools target API v3. Configure an Ahrefs API key; the integration sends
it as `Authorization: Bearer <api_key>`.

## Site Explorer

Use Site Explorer tools for backlink, organic, paid, and overview reports. Most
new tools accept a `params` object so agents can pass Ahrefs API fields such as
`target`, `date`, `mode`, `country`, `limit`, `offset`, `select`, and `where`
without the integration hiding upstream options.

```lua
local metrics = app.integrations.ahrefs.get_metrics({
  params = {
    target = "example.test",
    date = "2026-05-06",
    mode = "domain",
    country = "us",
  },
})

local dr = app.integrations.ahrefs.get_domain_rating({
  params = { target = "example.test", date = "2026-05-06" },
})

local backlinks = app.integrations.ahrefs.list_backlinks({
  target = "example.test",
  mode = "domain",
  limit = 25,
})

local broken = app.integrations.ahrefs.list_broken_backlinks({
  params = { target = "example.test", mode = "domain", limit = 25 },
})

local competitors = app.integrations.ahrefs.list_organic_competitors({
  params = { target = "example.test", mode = "domain", date = "2026-05-06", country = "us" },
})
```

Additional Site Explorer tools:

- `list_referring_domains({ target, limit?, offset?, mode? })`
- `list_organic_keywords({ target, limit?, offset?, mode? })`
- `list_pages({ target, limit?, offset?, mode? })`
- `list_paid_pages({ params })`
- `list_anchors({ target, limit?, offset? })`
- `list_linked_domains({ params })`
- `get_backlinks_stats({ params })`

## Subscription

```lua
local usage = app.integrations.ahrefs.get_limits_and_usage({})
```

This replaces the old current-user helper. Ahrefs API v3 documents subscription
limits and usage, not a `/users/me` profile endpoint.

## Generic API

Use `api_get` for Ahrefs API v3 endpoints without dedicated wrappers:

```lua
local result = app.integrations.ahrefs.api_get({
  path = "/v3/site-explorer/metrics-by-country",
  params = {
    target = "example.test",
    date = "2026-05-06",
    mode = "domain",
  },
})
```
Metadata-derived Lua example 
local result = app.integrations.ahrefs.list_backlinks({target = "example_target", limit = 1, offset = 1, mode = "example_mode"})
print(result)

Functions

list_referring_domains Read

List referring domains that link to a target website. Shows domain-level metrics like domain rating (DR), the number of backlinks from each domain, and first/last seen dates.

Lua path
app.integrations.ahrefs.list_referring_domains
Full name
ahrefs.ahrefs_list_referring_domains
ParameterTypeRequiredDescription
target string yes The target URL or domain to analyze (e.g., "example.com").
limit integer no Maximum number of referring domains to return (default: 100).
offset integer no Number of results to skip for pagination (default: 0).
mode string no Target matching mode: "domain", "subdomains", "exact", or "prefix". Default: "subdomains".
list_organic_keywords Read

List organic keywords that a target website or URL ranks for in search results. Returns keyword, position, search volume, traffic, keyword difficulty, and the ranking URL.

Lua path
app.integrations.ahrefs.list_organic_keywords
Full name
ahrefs.ahrefs_list_organic_keywords
ParameterTypeRequiredDescription
target string yes The target URL or domain to analyze (e.g., "example.com").
limit integer no Maximum number of keywords to return (default: 100).
offset integer no Number of results to skip for pagination (default: 0).
mode string no Target matching mode: "domain", "subdomains", "exact", or "prefix". Default: "subdomains".
list_pages Read

List top pages for a target website ranked by traffic or other metrics. Returns page URLs along with traffic data, keyword counts, and backlink information.

Lua path
app.integrations.ahrefs.list_pages
Full name
ahrefs.ahrefs_list_pages
ParameterTypeRequiredDescription
target string yes The target URL or domain to analyze (e.g., "example.com").
limit integer no Maximum number of pages to return (default: 100).
offset integer no Number of results to skip for pagination (default: 0).
mode string no Target matching mode: "domain", "subdomains", "exact", or "prefix". Default: "subdomains".
get_metrics Read

Get Site Explorer overview metrics for a target using Ahrefs API v3.

Lua path
app.integrations.ahrefs.get_metrics
Full name
ahrefs.ahrefs_get_metrics
ParameterTypeRequiredDescription
params object yes Query parameters such as target, date, mode, country, protocol, volume_mode, and select.
get_domain_rating Read

Get Domain Rating and Ahrefs Rank for a target and date.

Lua path
app.integrations.ahrefs.get_domain_rating
Full name
ahrefs.ahrefs_get_domain_rating
ParameterTypeRequiredDescription
params object yes Query parameters such as target, date, protocol, and output.
list_organic_competitors Read

List organic search competitors for a target.

Lua path
app.integrations.ahrefs.list_organic_competitors
Full name
ahrefs.ahrefs_list_organic_competitors
ParameterTypeRequiredDescription
params object yes Query parameters such as target, mode, date, country, limit, offset, and select.
list_paid_pages Read

List pages from a target ranking in paid search results.

Lua path
app.integrations.ahrefs.list_paid_pages
Full name
ahrefs.ahrefs_list_paid_pages
ParameterTypeRequiredDescription
params object yes Query parameters such as target, mode, date, country, limit, offset, and select.
list_linked_domains Read

List domains linked from the target.

Lua path
app.integrations.ahrefs.list_linked_domains
Full name
ahrefs.ahrefs_list_linked_domains
ParameterTypeRequiredDescription
params object yes Query parameters such as target, mode, limit, offset, select, and where.
list_anchors Read

List anchor texts used in backlinks pointing to a target website. Shows anchor text distribution, the number of referring pages using each anchor, and backlink counts.

Lua path
app.integrations.ahrefs.list_anchors
Full name
ahrefs.ahrefs_list_anchors
ParameterTypeRequiredDescription
target string yes The target URL or domain to analyze (e.g., "example.com").
limit integer no Maximum number of anchors to return (default: 100).
offset integer no Number of results to skip for pagination (default: 0).
get_limits_and_usage Read

Get Ahrefs API subscription limits and usage for the authenticated API key.

Lua path
app.integrations.ahrefs.get_limits_and_usage
Full name
ahrefs.ahrefs_get_limits_and_usage
ParameterTypeRequiredDescription
No parameters.
api_get Read

Call any Ahrefs API v3 GET endpoint.

Lua path
app.integrations.ahrefs.api_get
Full name
ahrefs.ahrefs_api_get
ParameterTypeRequiredDescription
path string yes API path such as /v3/site-explorer/metrics.
params object no Query parameters.