Skip to main content

Connect Ahrefs

Use an Ahrefs API v3 key to read Site Explorer and Keywords Explorer data from Python tasks in qbash. API requests use API units from the Ahrefs workspace that owns the key.

After you connect Ahrefs, you can add its tools to a qbash MCP server for ChatGPT, Claude and other MCP clients, or call it from a Python task. The Ahrefs MCP server page lists what the connector can do.

Create an Ahrefs API key​

  1. Sign in to the Ahrefs workspace that will pay for the API usage. API access is available on eligible paid plans; workspace owners and admins can check API access and usage in Account settings.
  2. Open Ahrefs API keys, then create a key for qbash. Give the key a descriptive name and set a per-key usage limit if your plan offers that control.
  3. Copy the key. Ahrefs displays it only when you create it. API keys expire one year after creation and are invalidated if the user who created them is removed from the workspace.

Ahrefs API keys and MCP keys are different credentials. Use the API key on this page for Python SDK methods. The separate Ahrefs chat connection uses an MCP key.

Add the key to qbash​

  1. In qbash, open Resources → Integrations and select Ahrefs.
  2. Add a credential name and paste the API v3 key, then save it.
  3. In a task editor, select the Ahrefs API-key credential under Resources → Integrations. A task uses only the credential selected for it.

Read keyword data​

report = qbash.integrations.ahrefs.organic_keywords(
    target="example.com",
    country="us",
    limit=100,
)
for keyword in report["keywords"]:
    print(keyword.get("keyword"), keyword.get("position"), keyword.get("volume"))

Replace example.com with the domain, subdomain, URL prefix, or URL you want to inspect. The method returns a bounded page. Ahrefs removed the offset parameter from API v3, so the connector cannot fetch a later page through offset or a cursor. Use the endpoint's filters and a smaller limit to keep requests focused.

API units and access​

Most API v3 report calls consume units from the connected Ahrefs workspace. Cost depends on the rows returned and the requested fields, with a 50-unit minimum for most paid requests. Keep limits small and select only the reads your task needs. Ahrefs provides a limited set of free test queries on paid plans, including Site Explorer requests for Ahrefs-owned domains and Keywords Explorer requests using only its documented test terms. Mixing other targets or terms can make a request billable.

If a call returns 401, create a replacement key and update the qbash credential. A 403 can mean the plan, API units, or requested resource does not allow that call; check Ahrefs access and usage settings before replacing a key. Workspace owners can revoke keys in Account settings.

See the Ahrefs API reference for endpoint fields and the API key guide for key lifecycle and usage controls.

Last updated on