SEO

List keyword recommendations

Which keywords to work on next, best first: each with its 0–100 score and the reasons, whether to create a new page or optimise an existing one (and which page), the kind of page, the search intent, an estimated click potential, the current position, and where the work stands.

GEThttps://api.vidrys.com/v1/projects/{project_id}/seo/recommendations

Plan: Track and above
Key: read
Rate cost: 1 unit

Scored from stored data — research metrics, Search Console impressions and positions, rank checks, the brand profile and the AI prompts the keyword matches — nightly and after every research lookup. Brand-name searches and keywords already ranking 1–3 are never recommended.

potential_clicks is an estimate from an industry click-through curve, labelled as such in potential_note; it is not a forecast.

Building the brief, drafting and publishing stay on the dashboard; the resulting content asset is readable here through get_content_brief and get_content_asset.

List keyword recommendations

curl --request GET \
  --url "https://api.vidrys.com/v1/projects/{project_id}/seo/recommendations" \
  --header "Authorization: Bearer $VIDRYS_API_KEY"

200 · success

{
  "recommendations": [
    {
      "id": "2b7e1f3a-9c4d-4e5f-8a6b-1c2d3e4f5a6b",
      "keyword_id": "7a1e9b2c-3d4f-4a5b-8c6d-0e1f2a3b4c5d",
      "keyword": "how to follow up on unpaid invoices",
      "score": 69,
      "evidence": [
        "1,300 searches a month",
        "Difficulty 24 of 100; not ranking in the top 20 yet",
        "Fits your topic 'late payments'",
        "No page on your site covers this. Closest: /blog/late-payment-fees (shares 1 of 4 words)"
      ],
      "intent": "informational",
      "action": "create",
      "action_label": "Create a how-to guide",
      "page_type": "how-to",
      "page_type_label": "How-to guide",
      "target_url": null,
      "potential_clicks": 91,
      "potential_note": "≈ +91 clicks a month at position 5 — an estimate from an industry click-through curve and the keyword's demand figure, not a forecast",
      "demand": 1300,
      "demand_basis": "search_volume",
      "position": null,
      "rank_at_recommendation": null,
      "rank_at_publish": null,
      "status": "recommended",
      "asset_id": null,
      "published_url": null,
      "published_at": null,
      "computed_at": "2026-10-02T03:30:00Z"
    }
  ],
  "counts": {
    "recommended": 12,
    "in_progress": 2,
    "published": 1,
    "dismissed": 3
  },
  "page": {
    "page": 1,
    "page_size": 50,
    "total": 15
  }
}

Authorization

Sent as a header on every request.

Authorizationstringrequired

A Vidrys API key, sent as Bearer vidrys_sk_…. A read key is enough. See Authentication.

Path parameters

project_idstringrequired

The project's id, from List projects.

Query parameters

statusstring

Only this status. Omit for every row.

Values:recommendedin_progresspublisheddismissed

pageintegerdefault 1

Page number, from 1.

page_sizeintegerdefault 50

Rows per page, 1–100.

Response · 200

application/json

recommendationsobject[]

Best first within each status: recommended, then in progress, published, dismissed.

+Show child attributes

idstring

Recommendation id.

keyword_idstring

The keyword's id, as list_seo_keywords returns it.

keywordstring

The search term.

scoreinteger

0–100: demand, attainability, fit to the brand, current standing and commercial value, weighted.

evidencestring[]

The reasons, as sentences, strongest first — what the card shows.

intentstring

What the searcher wants.

Values:informationalcommercialtransactional

actionstring

Create a new page, or optimise the page that already ranks or covers the term.

Values:createoptimize

action_labelstring

The action in words: "Create a how-to guide", "Optimise /pricing".

page_typestring

The deliverable: how-to, comparison, pricing, product, use-case, definition, faq, article, …

page_type_labelstring

The deliverable, as the dashboard names it.

target_urlstringnullable

Optimise: the existing page. Create: null until the page is published.

potential_clicksintegernullable

Monthly clicks the page could add at a modest target position — an estimate from an industry click-through curve, never a forecast. Null when no demand figure is known.

potential_notestringnullable

The estimate in words, with its basis and the caveat.

demandintegernullable

Monthly searches (research) or monthly-equivalent Search Console impressions — see demand_basis.

demand_basisstringnullable

Which figure demand is. Impressions are a floor on demand, not a volume.

Values:search_volumeimpressions

positionintegernullable

Latest Google position within the top 20; null when not in it.

rank_at_recommendationintegernullable

Position when the keyword was first recommended.

rank_at_publishintegernullable

Position when the page was published.

statusstring

Where the work stands. in_progress: a brief exists (see the content asset). published: live and rank-tracked.

Values:recommendedin_progresspublisheddismissed

asset_idstringnullable

The content asset holding the brief and draft, once one exists — read it with get_content_brief / get_content_asset.

published_urlstringnullable

The live page, once published.

published_atstringnullable

When, as an ISO 8601 timestamp (UTC).

computed_atstringnullable

When the score was last recomputed (nightly, and after each research lookup).

countsobject

Rows per status across the whole project, before paging.

pageobject

Where these rows sit in the full list.

+Show child attributes

pageinteger

This page's number, from 1.

page_sizeinteger

Rows per page.

totalinteger

Rows across every page.

Errors

403 plan_feature_unavailable	The feature is on a higher plan. Bulk exports and webhooks are Custom-only.
404 not_found	The project or item doesn't exist in this workspace. A project from another workspace also returns 404, never 403.
422 invalid_request	A parameter or body field is missing or has the wrong type or value. The message names the field. Also returned when a write would pass the plan's prompt limit.
401 unauthorized	No key was sent, or the key is unknown, revoked or expired, or the member who created it has left the workspace or been deactivated.
402 plan_required	The workspace's plan doesn't include API access. It's included on every plan from Track up — Solo is the one without it.
403 workspace_not_approved	The workspace is still waiting for approval, or wasn't approved.
429 rate_limited	Too many requests this minute. Wait for the number of seconds in the `Retry-After` header, then retry.

Every code, and what to retry, is in Errors.