KosmoKrator

seo

Ahrefs Lua API for KosmoKrator Agents

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

7 functions 7 read 0 write API key auth
Submit Ahrefs feedback View package source

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.

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 API Reference

List backlinks pointing to a target website or URL.

Parameters

NameTypeRequiredDescription
targetstringyesTarget URL or domain (e.g., "example.com")
limitintegernoMax results (default: 100)
offsetintegernoResults to skip for pagination (default: 0)
modestringnoTarget mode: "domain", "subdomain", "exact", "prefix" (default: "domain")

Target Modes

ModeDescription
domainMatch all subdomains of the domain (e.g., example.com matches www.example.com, blog.example.com)
subdomainMatch a specific subdomain (e.g., blog.example.com)
exactMatch the exact URL
prefixMatch all URLs starting with the given prefix

Example

local result = app.integrations.ahrefs.list_backlinks({
  target = "example.com",
  limit = 50,
  mode = "domain"
})

for _, link in ipairs(result.backlinks or {}) do
  print(link.url_from .. " -> " .. link.url_to)
end

list_referring_domains

List domains that link to a target.

Parameters

NameTypeRequiredDescription
targetstringyesTarget URL or domain
limitintegernoMax results (default: 100)
offsetintegernoResults to skip (default: 0)
modestringnoTarget mode (default: "domain")

Example

local result = app.integrations.ahrefs.list_referring_domains({
  target = "example.com",
  limit = 20
})

for _, domain in ipairs(result.referring_domains or {}) do
  print(domain.domain .. " (DR: " .. (domain.domain_rating or "N/A") .. ")")
end

list_organic_keywords

List organic keywords a target ranks for in search results.

Parameters

NameTypeRequiredDescription
targetstringyesTarget URL or domain
limitintegernoMax results (default: 100)
offsetintegernoResults to skip (default: 0)
modestringnoTarget mode (default: "domain")

Example

local result = app.integrations.ahrefs.list_organic_keywords({
  target = "example.com",
  limit = 30,
  mode = "domain"
})

for _, kw in ipairs(result.keywords or {}) do
  print(kw.keyword .. " — pos: " .. kw.position .. ", vol: " .. kw.volume)
end

list_pages

List top pages for a target website.

Parameters

NameTypeRequiredDescription
targetstringyesTarget URL or domain
limitintegernoMax results (default: 100)
offsetintegernoResults to skip (default: 0)
modestringnoTarget mode (default: "domain")

Example

local result = app.integrations.ahrefs.list_pages({
  target = "example.com",
  limit = 20
})

for _, page in ipairs(result.pages or {}) do
  print(page.url .. " — traffic: " .. page.traffic)
end

list_paid_keywords

List paid (PPC) keywords a target bids on.

Parameters

NameTypeRequiredDescription
targetstringyesTarget URL or domain
limitintegernoMax results (default: 100)
offsetintegernoResults to skip (default: 0)

Example

local result = app.integrations.ahrefs.list_paid_keywords({
  target = "example.com",
  limit = 20
})

for _, kw in ipairs(result.keywords or {}) do
  print(kw.keyword .. " — CPC: $" .. kw.cpc)
end

list_anchors

List anchor texts used in backlinks to a target.

Parameters

NameTypeRequiredDescription
targetstringyesTarget URL or domain
limitintegernoMax results (default: 100)
offsetintegernoResults to skip (default: 0)

Example

local result = app.integrations.ahrefs.list_anchors({
  target = "example.com",
  limit = 30
})

for _, anchor in ipairs(result.anchors or {}) do
  print(anchor.anchor .. " — refpages: " .. anchor.refpages)
end

get_current_user

Get the authenticated user’s profile information.

Parameters

None.

Example

local result = app.integrations.ahrefs.get_current_user({})
print("Logged in as: " .. result.email)

Multi-Account Usage

If you have multiple Ahrefs accounts configured, use account-specific namespaces:

-- Default account (always works)
app.integrations.ahrefs.function_name({...})

-- Explicit default (portable across setups)
app.integrations.ahrefs.default.function_name({...})

-- Named accounts
app.integrations.ahrefs.work.function_name({...})
app.integrations.ahrefs.client.function_name({...})

All functions are identical across accounts — only the credentials differ.

Raw agent markdown 
# Ahrefs — Lua API Reference

## list_backlinks

List backlinks pointing to a target website or URL.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `target` | string | yes | Target URL or domain (e.g., `"example.com"`) |
| `limit` | integer | no | Max results (default: 100) |
| `offset` | integer | no | Results to skip for pagination (default: 0) |
| `mode` | string | no | Target mode: `"domain"`, `"subdomain"`, `"exact"`, `"prefix"` (default: `"domain"`) |

### Target Modes

| Mode | Description |
|------|-------------|
| `domain` | Match all subdomains of the domain (e.g., `example.com` matches `www.example.com`, `blog.example.com`) |
| `subdomain` | Match a specific subdomain (e.g., `blog.example.com`) |
| `exact` | Match the exact URL |
| `prefix` | Match all URLs starting with the given prefix |

### Example

```lua
local result = app.integrations.ahrefs.list_backlinks({
  target = "example.com",
  limit = 50,
  mode = "domain"
})

for _, link in ipairs(result.backlinks or {}) do
  print(link.url_from .. " -> " .. link.url_to)
end
```

---

## list_referring_domains

List domains that link to a target.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `target` | string | yes | Target URL or domain |
| `limit` | integer | no | Max results (default: 100) |
| `offset` | integer | no | Results to skip (default: 0) |
| `mode` | string | no | Target mode (default: `"domain"`) |

### Example

```lua
local result = app.integrations.ahrefs.list_referring_domains({
  target = "example.com",
  limit = 20
})

for _, domain in ipairs(result.referring_domains or {}) do
  print(domain.domain .. " (DR: " .. (domain.domain_rating or "N/A") .. ")")
end
```

---

## list_organic_keywords

List organic keywords a target ranks for in search results.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `target` | string | yes | Target URL or domain |
| `limit` | integer | no | Max results (default: 100) |
| `offset` | integer | no | Results to skip (default: 0) |
| `mode` | string | no | Target mode (default: `"domain"`) |

### Example

```lua
local result = app.integrations.ahrefs.list_organic_keywords({
  target = "example.com",
  limit = 30,
  mode = "domain"
})

for _, kw in ipairs(result.keywords or {}) do
  print(kw.keyword .. " — pos: " .. kw.position .. ", vol: " .. kw.volume)
end
```

---

## list_pages

List top pages for a target website.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `target` | string | yes | Target URL or domain |
| `limit` | integer | no | Max results (default: 100) |
| `offset` | integer | no | Results to skip (default: 0) |
| `mode` | string | no | Target mode (default: `"domain"`) |

### Example

```lua
local result = app.integrations.ahrefs.list_pages({
  target = "example.com",
  limit = 20
})

for _, page in ipairs(result.pages or {}) do
  print(page.url .. " — traffic: " .. page.traffic)
end
```

---

## list_paid_keywords

List paid (PPC) keywords a target bids on.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `target` | string | yes | Target URL or domain |
| `limit` | integer | no | Max results (default: 100) |
| `offset` | integer | no | Results to skip (default: 0) |

### Example

```lua
local result = app.integrations.ahrefs.list_paid_keywords({
  target = "example.com",
  limit = 20
})

for _, kw in ipairs(result.keywords or {}) do
  print(kw.keyword .. " — CPC: $" .. kw.cpc)
end
```

---

## list_anchors

List anchor texts used in backlinks to a target.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `target` | string | yes | Target URL or domain |
| `limit` | integer | no | Max results (default: 100) |
| `offset` | integer | no | Results to skip (default: 0) |

### Example

```lua
local result = app.integrations.ahrefs.list_anchors({
  target = "example.com",
  limit = 30
})

for _, anchor in ipairs(result.anchors or {}) do
  print(anchor.anchor .. " — refpages: " .. anchor.refpages)
end
```

---

## get_current_user

Get the authenticated user's profile information.

### Parameters

None.

### Example

```lua
local result = app.integrations.ahrefs.get_current_user({})
print("Logged in as: " .. result.email)
```

---

## Multi-Account Usage

If you have multiple Ahrefs accounts configured, use account-specific namespaces:

```lua
-- Default account (always works)
app.integrations.ahrefs.function_name({...})

-- Explicit default (portable across setups)
app.integrations.ahrefs.default.function_name({...})

-- Named accounts
app.integrations.ahrefs.work.function_name({...})
app.integrations.ahrefs.client.function_name({...})
```

All functions are identical across accounts — only the credentials differ.

Metadata-Derived Lua Example

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

Functions

ahrefs_list_referring_domains

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.

Operation
Read read
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", "subdomain", "exact", "prefix". Default: "domain".

ahrefs_list_organic_keywords

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.

Operation
Read read
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", "subdomain", "exact", "prefix". Default: "domain".

ahrefs_list_pages

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.

Operation
Read read
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", "subdomain", "exact", "prefix". Default: "domain".

ahrefs_list_paid_keywords

List paid (PPC) keywords that a target website bids on in search advertising. Returns keyword, position, search volume, CPC, traffic, and the landing page URL.

Operation
Read read
Full name
ahrefs.ahrefs_list_paid_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).

ahrefs_list_anchors

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.

Operation
Read read
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).

ahrefs_get_current_user

Get the authenticated Ahrefs user's profile information. Returns account details like name, email, and subscription plan. Use this to verify API connectivity.

Operation
Read read
Full name
ahrefs.ahrefs_get_current_user
ParameterTypeRequiredDescription
No parameters.