visibility
POST /v1/visibility/targets/{targetId}/run
Run an audit now.
Authentication
Send an API key as a bearer token. The endpoint checks sites.create; a key without it is refused with 403, not 404.
This endpoint takes no organisation id. Your key already identifies the organisation it belongs to, and the response is scoped to it.
Try it
Replace anything in angle brackets with your own values, and the key placeholder with a key from your dashboard.
curl -X POST https://api.zinndigital.com/v1/visibility/targets/{targetId}/run \
-H "Authorization: Bearer zdk_live_…" \
-H "Content-Type: application/json" \
-d '{ "kind": <VisibilityAuditKind> }'Signed in? The API console in your dashboard fills in your real organisation id and your own key, and runs the request against the live API so you can see the actual response. Open this endpoint in the API console
Details
Starts an on-demand audit and returns 202 with a workflow id. The scheduled audit is included in the add-on; an on-demand run spends Zinn® credits, and the request is refused with 403 when the balance will not cover it. This is asynchronous by necessity, not by preference: one AI-visibility audit is a dozen provider calls and some answer engines take minutes. Poll the audit list for the result. The workflow id is deterministic per target and product, so pressing the button twice while a run is in flight costs one audit rather than two. A run after a finished one always starts. Rank tracking, product data and reputation measure only what the customer has supplied, so they are refused with 422 — before anything is spent — until the target has at least one search phrase, product or confirmed review profile respectively. A run a metered SEO allowance pays for — a site audit, a backlink refresh, a keyword list, a domain report, or a link-watch check — spends that allowance and no credit; once the month's allowance is used it is refused with 422 naming the allowance and the day it resets (see VisibilityPlan.allowances). Keyword research with no page_url reports the phrases the whole site is found for; with a page_url on the watched domain it reports the phrases that one page is found for (the audit summary's basis is site or page). A page on another host, or a page_url on any other kind, is refused with 422 before anything is spent.
Parameters
| Name | Type | Required | What it is |
|---|---|---|---|
targetId (path) | Uuid | Yes | The watched domain's id. |
Request body
| Name | Type | Required | What it is |
|---|---|---|---|
kind | VisibilityAuditKind | Yes | Which product an audit belongs to. ai_visibility — do the answer engines cite this site, and is it fit to be cited at all. reputation — ratings and recent reviews across… |
page_url | string | No | Keyword research only — one page of the watched site to research instead of the whole site, e.g. https://example.com/pricing/. Blank means the whole site. |
seed | string | No | Keyword research only — suggestions around one phrase, e.g. blue widgets. Blank means the site (or page_url) is the basis. |
location | string | No | Research kinds only (keyword_research, competitors, domain_score) — the market the question is asked in, in the customer's own words ("Germany", "de"), as on a tracked… |
language | string | No | Research kinds only — the results language for location. |
competitor | string | No | competitors only — one rival domain to draw a keyword-level gap against (the audit summary's gap; see SeoResearchInput.competitor). |
Response
| Name | Type | Required | What it is |
|---|---|---|---|
workflow_id | string | Yes | — |
kind | VisibilityAuditKind | Yes | Which product an audit belongs to. ai_visibility — do the answer engines cite this site, and is it fit to be cited at all. reputation — ratings and recent reviews across… |
target_id | string | Yes | — |
Errors this endpoint can return
401 · 403 · 404 · 422 · 503