SEO API — Documentazione API REST

Prodotto: SEO API · Versione API: v1 Base URL: https://seo.example.com/api/seo (alias versionato: https://seo.example.com/api/v1/seo) Autenticazione: Authorization: Bearer <API_KEY> Formato: JSON (UTF-8) · Aggiornato: 2026-06-30

Questa è la documentazione completa e ufficiale dell'API REST della suite SEO. Espone via API tutte le funzioni del prodotto: SEO Spider (crawl tecnico), GEO / AI Search (GEO audit, AI Visibility, AI Engine, AI Competitor, AI Prompt Research), Rank Tracker (progetti e keyword), Keyword Research, Google Search Console, Google Analytics e Alert.

Tutte le richieste richiedono un'API key valida (vedi Authentication) e sono soggette a rate-limit. Le risposte sono incapsulate in un oggetto {"data": ...}; gli elenchi includono un blocco meta di paginazione.

Indice

1. Introduzione e convenzioni
2. Base URL
3. Autenticazione
4. Rate limiting
5. Convenzioni (paginazione, CSV, wrapping)
6. Codici di errore standard
7. GET /status
8. GET / — Discovery
9. Account & Lookups (API key, locations, languages)
10. Rank Tracker — Progetti, Keyword, Keyword Research
11. SEO Spider
12. GEO & AI Search
13. Search Console, Analytics & Alerts

Introduction

The SEO API exposes the SEO suite over HTTP/JSON. A single controller sub-routes on the path segments after seo, giving programmatic access to:

• Rank Tracker — projects and their tracked keywords (positions + history).
• SEO Spider — site crawls (spider) and the crawled pages.
• GEO / AI — geo (GEO audits), ai-visibility, ai-engine, ai-competitor, and prompt-research.
• Keyword Research — keyword-research (DataForSEO-backed).
• Search Console & Analytics — search-console and analytics (live Google GSC + GA4 data).
• Alerts — alerts.

The discovery index (GET /) returns "name": "SEO API", "version": "v1".

Base URL

https://seo.example.com/api/seo

A versioned alias is also registered and served by the same controller:

https://seo.example.com/api/v1/seo

Both routes (seo and v1) are mapped to the same controller. When the request comes in under /api/v1/seo/..., the controller drops the leading seo version-prefix segment, so the two forms are equivalent (the literal seo is never treated as a resource name).

Resource names that contain multiple words use dashes in the URL (e.g. search-console, ai-visibility, keyword-research). The router normalizes dashes to underscores internally and the controller restores them, so dashed paths are the canonical form.

Authentication

All requests authenticate with a Bearer API key in the Authorization header. No cookies are used (CORS is enabled with Access-Control-Allow-Origin: *).

Authorization: Bearer <api_key>

The api_key comes from the user account. Two conditions must hold:

1. The API must be enabled globally by the administrator.
2. The user's plan must have the API enabled (plan_settings.api_is_enabled).

The API key is matched against an active user account (users.status = 1).

Auth example

curl -s https://seo.example.com/api/seo/status \
  -H "Authorization: Bearer YOUR_API_KEY"

Missing or invalid token

When the Authorization: Bearer header is missing, the API responds 401 with the "no bearer" error. When the token is present but does not match an active account (or the account's plan does not have the API enabled), the API responds 401 with the "no access" error. The error body follows the standard error envelope (see Conventions):

{
  "errors": [
    { "title": "...", "status": "401" }
  ]
}

If the API is globally disabled by the administrator, the request resolves to a 404 (the route is hidden) rather than a 401.

Rate limiting

Non-admin accounts are limited to 60 requests per 60 seconds per API key (a fixed-window counter keyed on the API key). Each response carries rate-limit headers:

When the limit is exceeded the API responds 429 (rate-limit error). Admin accounts (type = 1) are not rate-limited.

Some write/analysis endpoints enforce additional per-hour quotas (e.g. 30/hour for GEO, AI Engine, AI Visibility, AI Competitor and prompt research; 60/hour for keyword research). Hitting those quotas also returns 429.

Conventions

Response envelope

Successful responses are JSON wrapped in a top-level data key:

{ "data": ... }

List endpoints add a meta object:

{
  "data": [ ... ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total_results": 137,
    "total_pages": 6
  }
}

Error responses use a top-level errors array, each entry with title and status:

{
  "errors": [
    { "title": "Risorsa non trovata.", "status": "404" }
  ]
}

Pagination

List endpoints accept these query parameters:

meta.total_pages is computed as ceil(total_results / per_page).

CSV export

Any list endpoint can be exported as CSV by adding the query parameter:

?format=csv

When format=csv is set, the endpoint bypasses pagination and returns the full result set (capped at 5000 rows) as a file download rather than JSON. The response uses:

• Content-Type: text/csv; charset=UTF-8
• Content-Disposition: attachment; filename="<name>.csv"

The first row is the header (column names taken from the first record's keys). Array/object values are JSON-encoded into the cell; booleans become 1/0. Cell values are formula-injection-safe.

curl -s "https://seo.example.com/api/seo/projects?format=csv" \
  -H "Authorization: Bearer YOUR_API_KEY" -o projects.csv

CORS / preflight

OPTIONS preflight requests are answered (HTTP 204) before authentication. Allowed methods: GET, POST, PATCH, DELETE, OPTIONS. Allowed headers: Authorization, Content-Type.

Request body

Write endpoints accept either form-encoded bodies (application/x-www-form-urlencoded) or a raw JSON body.

Standard error codes

Additional statuses used by integration endpoints: 409 (Google/DataForSEO not configured or account not connected) and 502 (an upstream analysis or Google call failed).

GET /status

Returns the configuration/connection state for the calling account. No pagination.

Response fields

Example

curl -s https://seo.example.com/api/seo/status \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": {
    "dataforseo_configured": true,
    "google_configured": true,
    "google_connected": true,
    "google_email": "owner@example.com",
    "api_enabled": true
  }
}

GET / — Discovery index

GET /api/seo (the resource root, via GET) returns a discovery document describing the API.

Response fields

resources is:

status, projects, keywords, spider, geo, ai-visibility, ai-engine,
ai-competitor, prompt-research, keyword-research, search-console, analytics, alerts

Example

curl -s https://seo.example.com/api/seo \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": {
    "name": "SEO API",
    "version": "v1",
    "base_url": "https://seo.example.com/api/seo",
    "auth": "Authorization: Bearer <api_key>",
    "docs": "https://seo.example.com/api-docs",
    "resources": [
      "status", "projects", "keywords", "spider", "geo",
      "ai-visibility", "ai-engine", "ai-competitor", "prompt-research",
      "keyword-research", "search-console", "analytics", "alerts"
    ],
    "notes": "Liste paginate (?page=&per_page=, max 100); export CSV con ?format=csv; rate-limit 60/min; CORS abilitato."
  }
}

Account & Lookups

Account-level utilities and reference data. These are not listed in the discovery resources array but are fully supported resources.

GET /api-key — show the masked API key

Returns the caller's own API key, masked (first 4 + last 4 characters kept, the middle replaced by bullets). Useful for confirming which key is in use without exposing it.

Path: GET /api/seo/api-key

Response data: { "api_key_masked": "062d••…••ab" } (null if no key is set).

curl -s "https://seo.example.com/api/seo/api-key" \
  -H "Authorization: Bearer <api_key>"

POST /api-key/rotate — rotate the API key

Generates a new API key, stores it, and returns it in clear text (the only time it is shown in full). The old key stops working immediately — its cache entry is invalidated, so the next request with the old key returns 401.

Path: POST /api/seo/api-key/rotate

Response data: { "api_key": "<new_key>" }.

curl -s -X POST "https://seo.example.com/api/seo/api-key/rotate" \
  -H "Authorization: Bearer <current_api_key>"

After rotating, update your stored credential before making further calls — the rest of your session must use the new key.

GET /locations — location lookup

Looks up Google/DataForSEO geo targets (used for location_code on projects and keyword research). Requires the DataForSEO data source to be configured (409 otherwise).

Path: GET /api/seo/locations

Query parameters

Response data: array of location objects (as returned by the data source, e.g. location_code, location_name, country_iso_code). 502 if the upstream lookup fails.

curl -s "https://seo.example.com/api/seo/locations?country=IT&q=milan" \
  -H "Authorization: Bearer <api_key>"

GET /languages — language lookup

Returns supported language codes for projects / keyword research. Prefers the live data-source catalogue (cached ~24h) and falls back to a built-in list when the data source is unavailable, so it never errors.

Path: GET /api/seo/languages

Query parameters

Response data: array of { "code": "it", "name": "Italiano" } objects.

curl -s "https://seo.example.com/api/seo/languages?q=ital" \
  -H "Authorization: Bearer <api_key>"

Rank Tracker (Projects, Keywords, Keyword Research)

REST endpoints for managing rank-tracking projects, their tracked keywords, and ad-hoc keyword research.

• Base URL: https://seo.example.com/api/seo
• Versioned alias: the same controller also answers under /api/v1/seo/... (the leading seo/version segment is stripped before routing).
• Authentication: every request requires Authorization: Bearer <api_key>. The key is matched against an active user (users.api_key, status = 1); the user must also have a plan with API access enabled.
• Content type for writes: the body reader accepts either form-encoded ($_POST) data or a raw JSON body. JSON examples are used throughout (Content-Type: application/json).

Common response envelope

Success responses use a JSON:API-style envelope:

{ "data": { ... }, "meta": { ... } }

meta is only present on paginated list responses. Error responses use:

{ "errors": [ { "title": "message", "status": "404" } ] }

Common errors

All collections are scoped to the authenticated user (user_id). Operations on a project/keyword owned by another user return 404.

GET /projects — list projects

Returns the authenticated user's rank-tracker projects, newest first (ordered by project_id DESC).

Path: GET /api/seo/projects

Query parameters

Response data — array of project objects:

Response meta: page, per_page, total_results, total_pages.

Example

curl -s "https://seo.example.com/api/seo/projects?page=1&per_page=25" \
  -H "Authorization: Bearer <api_key>"

{
  "data": [
    {
      "id": 12,
      "name": "My Website",
      "domain": "example.com",
      "location_code": 2380,
      "language_code": "it",
      "keywords": 34,
      "gsc_property": "sc-domain:example.com",
      "ga4_property": "123456789",
      "last_datetime": "2026-06-12 03:15:02",
      "datetime": "2026-05-01 10:22:41"
    }
  ],
  "meta": { "page": 1, "per_page": 25, "total_results": 1, "total_pages": 1 }
}

GET /projects/{id} — get one project (with stats + keywords)

Returns a single project including its keywords and a 90-day stats summary computed locally.

Path: GET /api/seo/projects/{id}

Path params: id (int) — project ID.

Query parameters

Response data

keywords[] items

stats object (computed over rankings of the last 90 days)

Example

curl -s "https://seo.example.com/api/seo/projects/12" \
  -H "Authorization: Bearer <api_key>"

{
  "data": {
    "id": 12,
    "name": "My Website",
    "domain": "example.com",
    "location_code": 2380,
    "language_code": "it",
    "gsc_property": "sc-domain:example.com",
    "ga4_property": "123456789",
    "last_datetime": "2026-06-12 03:15:02",
    "datetime": "2026-05-01 10:22:41",
    "stats": {
      "tracked": 2,
      "ranking": 2,
      "avg_position": 7.5,
      "buckets": { "top3": 1, "top10": 1, "top20": 0, "top50": 0, "top100": 0, "none": 0 },
      "gained": [ { "keyword": "agenzia seo trento", "delta": 4, "from": 9, "to": 5 } ],
      "lost": [],
      "timeline": { "2026-06-10": 8.0, "2026-06-12": 7.5 }
    },
    "keywords": [
      {
        "id": 101,
        "keyword": "agenzia seo trento",
        "last_position": 5,
        "last_url": "https://example.com/seo",
        "search_volume": 320,
        "last_datetime": "2026-06-12 03:15:02"
      }
    ]
  }
}

Errors: 404 if the project does not exist or is not owned by the caller.

POST /projects — create a project

Creates a new rank-tracker project for the authenticated user.

Path: POST /api/seo/projects

Request body

Response: 201 Created with data: { "id": <new_project_id> }.

Example

curl -s -X POST "https://seo.example.com/api/seo/projects" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "My Website", "domain": "example.com", "location_code": 2380, "language_code": "it" }'

{ "data": { "id": 13 } }

Errors: 422 if name or domain is empty (I campi name e domain sono obbligatori.).

PATCH /projects/{id} — update a project

Partially updates a project. Only the fields present in the body are changed.

Path: PATCH /api/seo/projects/{id}

Path params: id (int).

Request body (all optional; at least one must be present)

Response: data: { "id": <project_id> }.

Example

curl -s -X PATCH "https://seo.example.com/api/seo/projects/12" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "My Website", "gsc_property": "sc-domain:example.com" }'

{ "data": { "id": 12 } }

Errors: 404 if not found/owned; 422 if no recognized field is supplied (Nessun campo da aggiornare.).

POST /projects/{id}/keywords — add keywords

Adds keywords to a project, de-duplicating case-insensitively against existing keywords and within the submitted batch.

Path: POST /api/seo/projects/{id}/keywords

Path params: id (int).

Request body — provide one of:

If keywords is a non-empty array it is used; otherwise keyword is split. At least one must yield a keyword. Matching is case-insensitive both against existing keywords and within the batch.

Response: 201 Created with counts.

Example (array form)

curl -s -X POST "https://seo.example.com/api/seo/projects/12/keywords" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{ "keywords": ["agenzia seo trento", "consulente seo", "agenzia seo trento"] }'

{ "data": { "added": 2, "skipped": 1, "removed": 0 } }

Example (replace the whole set)

curl -s -X POST "https://seo.example.com/api/seo/projects/12/keywords" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "replace", "keywords": ["agenzia seo trento", "consulente seo"] }'

Example (newline string form)

curl -s -X POST "https://seo.example.com/api/seo/projects/12/keywords" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{ "keyword": "agenzia seo trento\nconsulente seo" }'

Errors: 404 if project not found/owned; 422 if neither field yields a keyword (Fornire keyword (stringa) o keywords (array).).

POST /projects/{id}/refresh — refresh rankings

Triggers a synchronous refresh of all the project's keyword rankings via DataForSEO. Uses an internal claim + cooldown (~10 min) to avoid concurrent/duplicate refreshes.

Path: POST /api/seo/projects/{id}/refresh

Path params: id (int).

Request body: none.

Response: data: { "refreshed": <count> } — number of keywords successfully refreshed.

Example

curl -s -X POST "https://seo.example.com/api/seo/projects/12/refresh" \
  -H "Authorization: Bearer <api_key>"

{ "data": { "refreshed": 34 } }

Errors:

GET /projects/{id} keyword sub-resources

Project keywords are returned inline by GET /projects/{id}. Individual keyword operations live under the top-level /keywords resource (the keyword's own ID, not the project ID).

GET /keywords/{id}/history — keyword ranking history

Returns the position history for one keyword over a window of days.

Path: GET /api/seo/keywords/{id}/history

Path params: id (int) — keyword ID (must belong to the caller).

Query parameters

Response data

Each history[] item: { "position": int|null, "url": string|null, "datetime": "Y-m-d H:i:s" }.

Example

curl -s "https://seo.example.com/api/seo/keywords/101/history?days=30" \
  -H "Authorization: Bearer <api_key>"

{
  "data": {
    "keyword": "agenzia seo trento",
    "history": [
      { "position": 9, "url": "https://example.com/seo", "datetime": "2026-06-10 03:10:00" },
      { "position": 5, "url": "https://example.com/seo", "datetime": "2026-06-12 03:15:02" }
    ]
  }
}

DELETE /keywords/{id} — delete a keyword

Removes a single tracked keyword (and its rankings cascade).

Path: DELETE /api/seo/keywords/{id}

Path params: id (int) — keyword ID owned by the caller.

Response: data: { "id": <keyword_id> }.

curl -s -X DELETE "https://seo.example.com/api/seo/keywords/101" \
  -H "Authorization: Bearer <api_key>"

{ "data": { "id": 101 } }

Errors: 404 if the keyword does not exist or is not owned by the caller.

GET /keywords — list all tracked keywords

Lists every keyword tracked across the caller's projects (paginated), newest project first. Unlike the inline keyword list in GET /projects/{id}, this collection spans all projects and supports filtering and CSV export.

Path: GET /api/seo/keywords

Query parameters

Response data — array of keyword objects (same shape as GET /keywords/{id}):

curl -s "https://seo.example.com/api/seo/keywords?tag=priority&per_page=50" \
  -H "Authorization: Bearer <api_key>"

GET /keywords/{id} — get one keyword

Returns a single tracked keyword (owned by the caller), in the object shape above.

Path: GET /api/seo/keywords/{id} · Errors: 404 if not found/owned.

PATCH /keywords/{id} — update organisational fields

Updates only the organisational metadata of a keyword. The keyword text itself is not editable (it is unique per project and tied to billing/history).

Path: PATCH /api/seo/keywords/{id}

Body params (JSON or form-encoded; send at least one, else 422):

Response data: the updated keyword object (same shape as GET /keywords/{id}).

curl -s -X PATCH "https://seo.example.com/api/seo/keywords/101" \
  -H "Authorization: Bearer <api_key>" -H "Content-Type: application/json" \
  -d '{"tags":["priority","home"],"target_url":"https://example.com/seo","notes":"Landing page in review"}'

Errors: 404 (not found/owned); 422 if no updatable field (target_url, tags, notes) was supplied.

DELETE /keywords — bulk delete keywords

Deletes multiple keywords in a single call (scoped to the caller).

Path: DELETE /api/seo/keywords

Body params: ids — array of keyword IDs (also accepted as a comma-separated string, or an ?ids= query param). Foreign keywords are silently ignored (the WHERE is scoped to user_id).

Response: data: { "deleted": <count> }.

curl -s -X DELETE "https://seo.example.com/api/seo/keywords" \
  -H "Authorization: Bearer <api_key>" -H "Content-Type: application/json" \
  -d '{"ids":[101,102,103]}'

Errors: 422 if ids is missing/empty or contains no valid integer.

DELETE /projects/{id} — delete a project

Deletes the project; keywords and rankings cascade.

Path: DELETE /api/seo/projects/{id}

Response: data: { "id": <project_id> }.

curl -s -X DELETE "https://seo.example.com/api/seo/projects/12" \
  -H "Authorization: Bearer <api_key>"

Errors: 404 if not found/owned.

POST /keyword-research — keyword research

Runs an on-demand keyword research lookup against DataForSEO Labs: a seed-keyword overview plus related keywords and questions. Results are server-side cached per keyword + location_code + language_code.

Path: POST /api/seo/keyword-research

Request body

The ideas limit is fixed server-side (100); it is not a request parameter.

Rate limit: max 60 research calls per user per rolling hour (cache-based counter). Exceeding it returns 429.

Response: 201 Created.

Keyword metric object (used for seed and each item in related/questions)

Example

curl -s -X POST "https://seo.example.com/api/seo/keyword-research" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{ "keyword": "agenzia seo", "location_code": 2380, "language_code": "it" }'

{
  "data": {
    "seed": {
      "keyword": "agenzia seo",
      "search_volume": 2400,
      "cpc": 6.12,
      "competition": 0.71,
      "competition_level": "HIGH",
      "difficulty": 58,
      "intent": "commercial",
      "monthly_searches": [ { "year": 2026, "month": 5, "search_volume": 2400 } ],
      "serp_features": [ "people_also_ask", "local_pack" ],
      "opportunity": 41.3
    },
    "related": [
      {
        "keyword": "agenzia seo trento",
        "search_volume": 320,
        "cpc": 4.05,
        "competition": 0.44,
        "competition_level": "MEDIUM",
        "difficulty": 27,
        "intent": "commercial",
        "monthly_searches": [],
        "serp_features": [ "local_pack" ],
        "opportunity": 63.0
      }
    ],
    "questions": [
      {
        "keyword": "cosa fa un'agenzia seo",
        "search_volume": 90,
        "cpc": null,
        "competition": null,
        "competition_level": null,
        "difficulty": 12,
        "intent": "informational",
        "monthly_searches": [],
        "serp_features": [ "people_also_ask" ],
        "opportunity": 70.0
      }
    ],
    "location_code": 2380,
    "language_code": "it",
    "generated_at": "2026-06-13 11:04:22"
  }
}

Errors:

SEO Spider

Endpoints for crawling a website and retrieving the resulting SEO audit (scans, crawled pages and issue breakdowns).

Base URL: https://seo.example.com/api/seo Authentication: all requests require a Bearer token.

Authorization: Bearer <api_key>

Conventions

• List endpoints are paginated with ?page= (default 1) and ?per_page= (default 25, max 100).
• List endpoints also support CSV export with ?format=csv (returns text/csv as a file download; up to 5000 rows in a single shot, no pagination).
• Rate limit: 60 requests/minute. CORS is enabled.
• Successful single-resource responses use a JSON:API style envelope: { "data": { ... } }.
• Successful list responses use { "data": [ ... ], "meta": { page, per_page, total_results, total_pages } }.

GET /spider

List the SEO Spider scans belonging to the authenticated user, newest first (ordered by scan_id DESC).

Query parameters

Per-scan fields (summary shape)

curl

curl -s "https://seo.example.com/api/seo/spider?page=1&per_page=25" \
  -H "Authorization: Bearer <api_key>"

Example response

{
  "data": [
    {
      "id": 42,
      "name": "Crawl example.com",
      "host": "example.com",
      "status": "completed",
      "score": 78,
      "pages_found": 312,
      "pages_processed": 312,
      "errors_count": 9,
      "warnings_count": 41,
      "started_datetime": "2026-06-13 09:14:02",
      "finished_datetime": "2026-06-13 09:31:55",
      "datetime": "2026-06-13 09:14:01"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total_results": 1,
    "total_pages": 1
  }
}

GET /spider/{id}

Retrieve a single scan (detail shape). Returns the same fields as the list shape, plus — only while status is crawling — a pending field with the number of URLs still queued.

Path parameters

Additional field (detail, crawling only)

curl

curl -s "https://seo.example.com/api/seo/spider/42" \
  -H "Authorization: Bearer <api_key>"

Example response (in progress)

{
  "data": {
    "id": 42,
    "name": "Crawl example.com",
    "host": "example.com",
    "status": "crawling",
    "score": null,
    "pages_found": 120,
    "pages_processed": 75,
    "errors_count": 2,
    "warnings_count": 18,
    "started_datetime": "2026-06-13 09:14:02",
    "finished_datetime": null,
    "datetime": "2026-06-13 09:14:01",
    "pending": 45
  }
}

Errors

GET /spider/{id}/issues

Aggregated issue breakdown across all crawled pages of a scan. Counts each issue code's occurrences and rolls them up by severity.

Path parameters

Response fields

Each issues[] entry:

Issue codes by severity (from SpiderService::SEVERITY)

• major: status_4xx, status_5xx, title_missing, h1_missing, h1_multiple, not_https, fetch_failed
• moderate: meta_desc_missing, page_heavy, response_slow, no_viewport, low_words, mixed_content, compression_off, canonical_missing, status_3xx, redirect_chain, dom_too_large, render_blocking
• minor: title_short, title_long, meta_desc_long, images_no_alt, url_too_long, url_params, url_uppercase, url_http, no_schema, no_og, blocked_robots, nofollow, no_doctype, lang_missing, charset_missing, no_favicon, deprecated_html, no_twitter, noindex, email_exposed, no_hsts, no_security_headers

Note: the API response does not include a per-issue fix field — only code, severity, and pages.

curl

curl -s "https://seo.example.com/api/seo/spider/42/issues" \
  -H "Authorization: Bearer <api_key>"

Example response

{
  "data": {
    "by_severity": {
      "major": 11,
      "moderate": 53,
      "minor": 128
    },
    "issues": [
      { "code": "images_no_alt",     "severity": "minor",    "pages": 64 },
      { "code": "meta_desc_missing", "severity": "moderate", "pages": 30 },
      { "code": "title_missing",     "severity": "major",    "pages": 6 }
    ]
  }
}

Errors

GET /spider/{id}/pages

List the crawled pages of a scan, paginated, ordered by page_id ascending.

Path parameters

Query parameters

Per-page fields

Note the JSON key names differ from the underlying columns: internal_links_count is returned as internal_links and external_links_count as external_links.

curl

# All pages
curl -s "https://seo.example.com/api/seo/spider/42/pages?page=1&per_page=50" \
  -H "Authorization: Bearer <api_key>"

# Only pages with issues
curl -s "https://seo.example.com/api/seo/spider/42/pages?issues=1" \
  -H "Authorization: Bearer <api_key>"

# Only 404 pages
curl -s "https://seo.example.com/api/seo/spider/42/pages?status=404" \
  -H "Authorization: Bearer <api_key>"

# CSV export
curl -s "https://seo.example.com/api/seo/spider/42/pages?format=csv" \
  -H "Authorization: Bearer <api_key>" -o spider_pages.csv

Example response

{
  "data": [
    {
      "id": 1501,
      "url": "https://example.com/services/",
      "status_code": 200,
      "score": 82,
      "title": "Services - My Website",
      "meta_description": "I nostri servizi di sviluppo e SEO.",
      "h1": "I nostri servizi",
      "canonical": "https://example.com/services/",
      "is_indexable": true,
      "is_noindex": false,
      "words_count": 642,
      "images_no_alt": 2,
      "internal_links": 38,
      "external_links": 4,
      "schema_types": "Organization,WebPage",
      "issues": ["images_no_alt", "meta_desc_long"]
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 50,
    "total_results": 1,
    "total_pages": 1
  }
}

Errors

POST /spider

Start a new crawl. Returns immediately with the new scan id; crawling proceeds asynchronously (driven by cron + live polling), so poll GET /spider/{id} to track progress.

Request body (JSON)

Success response — HTTP 201:

curl

curl -s -X POST "https://seo.example.com/api/seo/spider" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Crawl example.com",
    "start_url": "https://example.com/",
    "max_pages": 500,
    "max_depth": 10,
    "speed": "fast",
    "include_subdomains": false,
    "respect_robots": true,
    "use_sitemap": true,
    "exclude_paths": "/wp-admin/\n/cart/"
  }'

Example response

{
  "data": {
    "id": 43,
    "status": "crawling"
  }
}

Errors

POST /spider/{id}/rescan

Re-crawls the same scan in place: the scan_id is preserved and the previous crawl is kept as a history snapshot (so you can compare before/after). Sets the scan back to crawling.

Path: POST /api/seo/spider/{id}/rescan

Success response: data: { "id": <scan_id>, "status": "crawling" }.

curl -s -X POST "https://seo.example.com/api/seo/spider/43/rescan" \
  -H "Authorization: Bearer <api_key>"

Errors: 404 (not found/owned); 422 if the re-crawl could not be started.

PATCH /spider/{id} — rename a scan

Renames a scan. Only the name field is updatable.

Path: PATCH /api/seo/spider/{id}

Body params: name (required, non-empty, trimmed to 255 chars).

Success response: data: { "id": <scan_id>, "name": "<new name>" }.

curl -s -X PATCH "https://seo.example.com/api/seo/spider/43" \
  -H "Authorization: Bearer <api_key>" -H "Content-Type: application/json" \
  -d '{"name":"Homepage crawl — June"}'

Errors: 404 (not found/owned); 422 if name is missing or empty.

GET /spider/{id}/history — per-crawl snapshots

Returns the immutable history of every completed crawl of this scan (one snapshot per crawl), oldest first. Useful for trend charts and diffing.

Path: GET /api/seo/spider/{id}/history

Response data — array of snapshot objects:

curl -s "https://seo.example.com/api/seo/spider/43/history" \
  -H "Authorization: Bearer <api_key>"

Errors: 404 if the scan is not found/owned.

GET /spider/{id}/compare — diff two scans

Compares this scan against another of the caller's scans (matched page-by-page via URL hash) and reports what was added, removed, and changed.

Path: GET /api/seo/spider/{id}/compare?to={id2}

Query parameters

Response data

curl -s "https://seo.example.com/api/seo/spider/43/compare?to=41" \
  -H "Authorization: Bearer <api_key>"

Errors: 422 if to is missing; 404 if either scan is not found/owned.

DELETE /spider/{id}

Delete a scan. Cascades to its crawled pages, queue, and link records.

Path parameters

Success response

curl

curl -s -X DELETE "https://seo.example.com/api/seo/spider/43" \
  -H "Authorization: Bearer <api_key>"

Example response

{
  "data": {
    "id": 43
  }
}

Errors

GEO & AI Search

REST endpoints for the Generative Engine Optimization (GEO) and AI-search modules of the suite. These five resources share a common implementation (resource_config() + generic_resource() + run_action()), so their request/response shapes follow the same pattern; only the table, fields and POST runner differ.

• Base URL: https://seo.example.com/api/seo
• Auth: Authorization: Bearer <api_key> (required on every request)
• Content-Type for POST bodies: application/json (form-encoded $_POST is also accepted)

Resources at a glance

Common behaviour (all five resources)

These rules are enforced by the shared generic_resource() / cast_row() logic and apply identically to every resource below.

Scoping. All rows are scoped to the authenticated user (WHERE user_id = <uid>). The user_id column is stripped from single-item responses.

ID normalization (cast_row). The native id column (audit_id, run_id, test_id, report_id, prompt_id) is renamed to id and cast to integer in every response. The following columns, when present, are cast to integer: geo_score, score, prompts_total, cited_count, first_count, pages_count. has_llms_txt is cast to boolean. avg_position is cast to float.

GET /{resource} (list). Returns the list columns defined per resource (see each section), ordered by id column DESC, paginated.

• Query params: ?page (default 1), ?per_page (default 25, clamped to 1–100).
• ?format=csv exports the whole set (capped at 5000 rows) as a CSV download instead of a JSON page.

GET /{resource}/{id} (single item). Returns the full DB row (all columns), with id normalization applied and user_id removed. Any of these JSON payload columns, when present and stored as a string, are decoded into objects before being returned: result, checks, recommendations, ai_crawlers, competitors. Returns 404 if no matching row for the user.

POST /{resource} (create / run). There is no plain insert — a POST to the collection triggers the resource's analysis runner (run_action), which is the costly operation (OpenAI / DataForSEO). On success it returns the freshly produced result with HTTP 201. Each runner is rate-limited to 30 runs/hour per user (429 when exceeded). Validation failures return 422; analysis failures return 502.

DELETE /{resource}/{id}. Not supported for these five resources — generic_resource() only handles GET (list / single) and POST (run). A DELETE will not match and is not routed here.

GEO — Generative Engine Optimization audit

geo audits a URL for how well it is optimized for generative/AI engines (LLM-friendliness): page count, presence of an llms.txt, and a computed GEO score.

Resource id: audit_id

GET /geo — list

List columns: audit_id (→ id), host, url, geo_score, has_llms_txt, pages_count, datetime.

curl -H "Authorization: Bearer <api_key>" \
  "https://seo.example.com/api/seo/geo?page=1&per_page=25"

{
  "data": [
    {
      "host": "example.com",
      "url": "https://example.com/",
      "geo_score": 72,
      "has_llms_txt": true,
      "pages_count": 18,
      "datetime": "2026-06-13 10:42:11",
      "id": 14
    }
  ]
}

GET /geo/{id} — single audit

Returns the full row; checks, recommendations and ai_crawlers JSON columns (when present) are decoded.

curl -H "Authorization: Bearer <api_key>" \
  "https://seo.example.com/api/seo/geo/14"

POST /geo — run an audit

Body params read by the runner:

* At least one of url / domain must be a non-empty string, otherwise 422 (Il campo url è obbligatorio.).

Runs GeoAuditService::audit($url, $uid). Returns 201 with the audit result, or 502 (Audit non riuscito.) if the service returns null.

curl -X POST -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/"}' \
  "https://seo.example.com/api/seo/geo"

AI Visibility — brand presence across AI engines

ai-visibility measures how often and how prominently a brand is cited by AI engines across a set of prompts: citation counts, first-mention counts, average position and an overall score, per engine.

Resource id: run_id

GET /ai-visibility — list

List columns: run_id (→ id), brand, host, engine, score, prompts_total, cited_count, first_count, avg_position, datetime.

curl -H "Authorization: Bearer <api_key>" \
  "https://seo.example.com/api/seo/ai-visibility?per_page=50"

{
  "data": [
    {
      "brand": "Acme",
      "host": "acme.com",
      "engine": "openai",
      "score": 64,
      "prompts_total": 10,
      "cited_count": 6,
      "first_count": 2,
      "avg_position": 1.83,
      "datetime": "2026-06-13 09:15:00",
      "id": 7
    }
  ]
}

GET /ai-visibility/{id} — single run

Returns the full row; result JSON column (when present) is decoded.

POST /ai-visibility — run an analysis

Body params read by the runner:

Runs AiVisibilityService::analyze($brand, $domain, $prompts, $uid, $topic). Returns 201 with the result, or 502 with the service error message ($svc->error or Analisi non riuscita.).

curl -X POST -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
        "brand": "Acme",
        "domain": "acme.com",
        "topic": "industrial pumps",
        "prompts": ["best industrial pump brands", "who makes reliable pumps"]
      }' \
  "https://seo.example.com/api/seo/ai-visibility"

AI Engine — keyword/URL AI-readiness test

ai-engine tests how a specific URL performs for a given keyword from an AI-engine perspective, producing a score.

Resource id: test_id

GET /ai-engine — list

List columns: test_id (→ id), keyword, url, score, datetime.

curl -H "Authorization: Bearer <api_key>" \
  "https://seo.example.com/api/seo/ai-engine"

{
  "data": [
    {
      "keyword": "industrial pumps",
      "url": "https://acme.com/pumps",
      "score": 58,
      "datetime": "2026-06-13 11:02:44",
      "id": 3
    }
  ]
}

GET /ai-engine/{id} — single test

Returns the full row; result JSON column (when present) is decoded.

POST /ai-engine — run a test

Body params read by the runner:

Runs AiEngineService::analyze($keyword, $url, $uid). Returns 201 with the result, or 502 with the service error message.

curl -X POST -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"keyword":"industrial pumps","url":"https://acme.com/pumps"}' \
  "https://seo.example.com/api/seo/ai-engine"

AI Competitor — brand vs competitors AI report

ai-competitor generates a comparative report of a brand against one or more competitors as seen by AI engines.

Resource id: report_id

GET /ai-competitor — list

List columns: report_id (→ id), brand, competitors, datetime.

curl -H "Authorization: Bearer <api_key>" \
  "https://seo.example.com/api/seo/ai-competitor"

{
  "data": [
    {
      "brand": "Acme",
      "competitors": "Globex, Initech",
      "datetime": "2026-06-13 08:30:00",
      "id": 2
    }
  ]
}

GET /ai-competitor/{id} — single report

Returns the full row; competitors and result JSON columns (when present) are decoded.

POST /ai-competitor — run a report

Body params read by the runner:

Default (single-subject) mode. Returns 201 with the analysis of brand measured against the given competitors, or 502 with the service error message. Rate limited to 30 runs/hour per user (429 when exceeded).

curl -X POST -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"brand":"Acme","competitors":"Globex, Initech","language":"English"}' \
  "https://seo.example.com/api/seo/ai-competitor"

Matrix mode — symmetric N-way analysis

With {"mode":"matrix"} (or "symmetric":true, or ?symmetric=1) every participant — the subject brand plus each competitor — is analysed in turn as the subject, then the runs are merged into a single symmetric report. This yields a comparable score for each brand rather than a one-directional "us vs. them" view. Rate-limiting and spend caps are enforced internally by the matrix runner (it is not double rate-limited).

curl -X POST -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"mode":"matrix","brand":"Acme","competitors":["Globex","Initech"],"language":"English"}' \
  "https://seo.example.com/api/seo/ai-competitor"

The matrix response is an object keyed on the participating brands. Its exact fields come from AiCompetitorService::analyze_matrix(), but it is shaped around a brands list (each brand with its aggregated score/metrics across all runs) and a pairwise matrix block (how each brand fares against each other brand). Example (abridged):

{
  "data": {
    "mode": "matrix",
    "brands": [
      { "brand": "Acme",   "score": 71, "cited": 12, "first": 4 },
      { "brand": "Globex", "score": 63, "cited": 9,  "first": 2 },
      { "brand": "Initech","score": 58, "cited": 7,  "first": 1 }
    ],
    "matrix": [
      { "subject": "Acme",   "vs": { "Globex": 0.6, "Initech": 0.7 } },
      { "subject": "Globex", "vs": { "Acme": 0.4,   "Initech": 0.55 } },
      { "subject": "Initech","vs": { "Acme": 0.3,   "Globex": 0.45 } }
    ]
  }
}

The concrete keys/values are produced by the service; treat the block above as the shape (a per-brand summary list + a pairwise comparison block), not a fixed contract.

On failure the endpoint returns 502, or 429 when the internal quota/spend limit is hit (the error message contains limite).

AI Prompt Research — prompt expansion / research

prompt-research expands a seed prompt into research output (e.g. related AI-search prompts/variations) for a given language.

Resource id: prompt_id

Note: Prompt Research uses its own cache-based hourly limiter (pr_rate_<uid>, 30/hour) instead of the shared table rate guard, and analyze() is called without a user id.

GET /prompt-research — list

List columns: prompt_id (→ id), prompt, language, datetime.

curl -H "Authorization: Bearer <api_key>" \
  "https://seo.example.com/api/seo/prompt-research"

{
  "data": [
    {
      "prompt": "best CRM for small business",
      "language": "en",
      "datetime": "2026-06-13 12:00:00",
      "id": 9
    }
  ]
}

GET /prompt-research/{id} — single item

Returns the full row; result JSON column (when present) is decoded.

POST /prompt-research — run research

Body params read by the runner:

Runs PromptResearchService::analyze($prompt). Returns 201 with the result, or 502 with the service error message. Rate limited to 30 runs/hour per user (429 when exceeded).

curl -X POST -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"best CRM for small business"}' \
  "https://seo.example.com/api/seo/prompt-research"

Search Console, Analytics & Alerts

Base URL: https://seo.example.com/api/seo Auth (all endpoints): Authorization: Bearer <api_key>

Google connection requirement (search-console & analytics)

Both /search-console and /analytics call google_client() before doing anything else. This returns errors (and stops the request) in three cases:

• 409 — Integrazione Google non configurata dall'amministratore. — the Google OAuth integration has not been configured at the admin level (Google is not configured at the admin level).
• 409 — Account Google non collegato. Collegalo dal pannello (Search Console). — the authenticated user has not linked their Google account.
• 502 — token could not be obtained / refresh error (the client error message is returned, e.g. Account Google non collegato.).

If a downstream Google API call fails after connection, the endpoint also returns 502 with the Google client error message.

Shared date window (range)

Both Google endpoints use the same window logic:

• Optional query param range = number of days. Allowed values: 7, 28, 90. Any other / missing value defaults to 28.
• Google data lags ~2 days, so the window is shifted back by 2 days and is inclusive:
  • end = today − 2 days
  • start = today − (2 + range − 1) days
• The response echoes range_days, start, and end.

GET /search-console

Live Google Search Console performance for one verified site/property.

Sub-resource: list sites

GET /api/seo/search-console/sites

Returns a flat JSON array of the site URLs available to the connected Google account (the siteUrl values, e.g. sc-domain:example.com or https://example.com/). The site list is cached for 6 hours per user.

Main report

GET /api/seo/search-console

Query parameters

Passing dimensions switches the endpoint into custom query mode (see below), which changes the response shape.

422 case

If site is missing (and the account does not have exactly one site to auto-select) or is not a valid site for the account:

• 422 — Parametro "site" mancante o non valido. Vedi GET /api/seo/search-console/sites.

Response (data object)

totals object:

Each row in queries and pages (GSC row shape):

The full report bundle is cached for 3 hours per (user, site, start, end).

curl

curl -s "https://seo.example.com/api/seo/search-console?site=sc-domain:example.com&range=28" \
  -H "Authorization: Bearer <api_key>"

Example response

{
  "data": {
    "site": "sc-domain:example.com",
    "range_days": 28,
    "start": "2026-06-01",
    "end": "2026-06-28",
    "totals": {
      "clicks": 1234,
      "impressions": 56789,
      "ctr": 2.17,
      "position": 14.3
    },
    "queries": [
      { "key": "esempio keyword", "clicks": 210, "impressions": 4300, "ctr": 4.88, "position": 6.2 },
      { "key": "altra query",     "clicks": 95,  "impressions": 2100, "ctr": 4.52, "position": 9.8 }
    ],
    "pages": [
      { "key": "https://example.com/", "clicks": 540, "impressions": 12000, "ctr": 4.5, "position": 7.1 }
    ]
  }
}

Custom query mode (dimensions)

When dimensions is supplied, the endpoint runs an arbitrary Search Analytics query instead of the default bundle and returns a flat rows list.

Response data (custom mode): site, range_days, dimensions (the applied list), search_type, and rows — each row { "keys": [...], "clicks": int, "impressions": int, "ctr": float, "position": float } where keys aligns with the requested dimensions.

curl -s "https://seo.example.com/api/seo/search-console?site=sc-domain:example.com&dimensions=query,page&query_filter=seo&row_limit=100" \
  -H "Authorization: Bearer <api_key>"

GET /analytics

Live Google Analytics 4 (GA4) report for one property.

Sub-resource: list properties

GET /api/seo/analytics/properties

Returns a JSON array of the raw GA4 property objects available to the connected account (each contains a property field like properties/123456789). Cached for 6 hours per user.

Main report

GET /api/seo/analytics

Query parameters

422 case

If property is missing (and there isn't exactly one property to auto-select) or does not match a property of the account:

• 422 — Parametro "property" mancante o non valido. Vedi GET /api/seo/analytics/properties.

Response (data object)

totals object:

Each row in top_pages:

The bundle is cached for 3 hours per (user, property, start, end).

curl

curl -s "https://seo.example.com/api/seo/analytics?property=123456789&range=7" \
  -H "Authorization: Bearer <api_key>"

Example response

{
  "data": {
    "property": "123456789",
    "range_days": 7,
    "start": "2026-06-22",
    "end": "2026-06-28",
    "totals": {
      "sessions": 4821,
      "active_users": 3990,
      "new_users": 2700,
      "page_views": 11230,
      "engagement_rate": 62.4,
      "avg_session_duration": 95.7
    },
    "top_pages": [
      { "page": "/", "views": 3120 },
      { "page": "/blog/articolo", "views": 880 }
    ]
  }
}

Custom report mode (metrics)

When metrics is supplied, the endpoint runs an arbitrary GA4 report instead of the default bundle. Metric and dimension names are whitelist-validated.

Response data (custom mode): property, range_days, metrics (applied list), dimensions (applied list), and rows — each row is a flat object with one key per requested dimension (string) and one key per requested metric (number).

curl -s "https://seo.example.com/api/seo/analytics?property=123456789&metrics=sessions,activeUsers&dimensions=country&order_by=sessions&limit=20" \
  -H "Authorization: Bearer <api_key>"

/alerts

Local SEO alerts for the authenticated user. Does not require a Google connection.

GET /alerts — list alerts

GET /api/seo/alerts

Query parameters

Results are ordered by datetime descending.

Response — one object per alert

Pagination (meta)

List responses include a meta block:

"meta": {
  "page": 1,
  "per_page": 25,
  "total_results": 137,
  "total_pages": 6
}

curl

curl -s "https://seo.example.com/api/seo/alerts?is_read=0&page=1&per_page=25" \
  -H "Authorization: Bearer <api_key>"

CSV export:

curl -s "https://seo.example.com/api/seo/alerts?format=csv" \
  -H "Authorization: Bearer <api_key>" -o alerts.csv

Example response

{
  "data": [
    {
      "id": 482,
      "type": "ranking_drop",
      "severity": "high",
      "message": "La keyword \"esempio\" e scesa di 12 posizioni.",
      "is_read": false,
      "datetime": "2026-06-29 08:14:02"
    },
    {
      "id": 481,
      "type": "new_backlink",
      "severity": "info",
      "message": "Rilevato un nuovo backlink da example.org.",
      "is_read": true,
      "datetime": "2026-06-28 22:01:11"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total_results": 137,
    "total_pages": 6
  }
}

PATCH /alerts — mark read / unread

Mark a single alert, or all of the user's alerts, as read or unread.

PATCH /api/seo/alerts/{id}    # one alert
PATCH /api/seo/alerts         # all alerts for the user

Request body (JSON)

Responses

• Single alert: if {id} does not belong to the user, returns 404. On success returns { "id": <id>, "is_read": <bool> }.
• All alerts (no id): returns { "updated": "all", "is_read": <bool> }.

curl

# mark one alert read
curl -s -X PATCH "https://seo.example.com/api/seo/alerts/482" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"is_read": true}'

# mark all alerts read
curl -s -X PATCH "https://seo.example.com/api/seo/alerts" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"is_read": true}'

Documentazione dell'API REST della SEO API.

Novità — endpoint aggiunti/estesi (aggiornamento 2026-07)

Questa release aggiunge nuovi endpoint e parametri all'API. Autenticazione e convenzioni invariate.

Account — rotazione API key

• GET /api/seo/api-key → chiave mascherata ({"api_key_masked":"062d••…••ab"}).
• POST /api/seo/api-key/rotate → genera una nuova API key e la restituisce ({"api_key":"…"}). La vecchia chiave smette immediatamente di funzionare (401).

Lookup location & lingue

• GET /api/seo/locations?q=<testo>&country=<ISO2>&limit=100 → location Google. Senza country = elenco Paesi; con country=IT = città/regioni di quel Paese (es. Milano). Richiede DataForSEO (409 altrimenti).
• GET /api/seo/languages?q=<testo> → elenco codici lingua supportati (code, name).

Keyword — nuove operazioni e campi

• GET /api/seo/keywords → tutte le keyword tracciate dei progetti dell'utente (paginato; filtri ?project_id=, ?tag=; ?format=csv).
• GET /api/seo/keywords/{id} → dettaglio di una singola keyword.
• PATCH /api/seo/keywords/{id} → aggiorna solo i campi organizzativi: target_url, tags (array o stringa CSV), notes. (Il testo della keyword NON è modificabile.)
• DELETE /api/seo/keywords con body {"ids":[1,2,3]} → eliminazione massiva (una sola chiamata).
• Nuovi campi in tutte le risposte keyword: target_url, tags (array), notes.

Progetti

• GET /api/seo/projects/{id}?format=csv → export CSV delle keyword del progetto (una riga per keyword).
• POST /api/seo/projects/{id}/keywords con {"mode":"replace", "keywords":[…]} → sostituisce l'intero set di keyword (risposta {added, removed, skipped}). Senza mode, comportamento invariato (append + dedup).

SEO Spider

• POST /api/seo/spider/{id}/rescan → ri-scansiona lo stesso dominio mantenendo scan_id e lo storico (per confronto pre/post).
• GET /api/seo/spider/{id}/history → snapshot immutabili di ogni crawl completato (score, pagine, errori/warning, codici stato, durata).
• PATCH /api/seo/spider/{id} con {"name":"…"} → rinomina una scansione.
• GET /api/seo/spider/{id}/compare?to={id2} → confronto tra due scansioni dell'utente: summary (pagine nuove/perse/cambiate, score_delta) + liste added_pages, removed_pages, changed_pages (delta status/score/issues/indicizzabilità per URL).

Search Console — filtri avanzati

GET /api/seo/search-console?site=… accetta ora (modalità custom):

• dimensions (CSV tra: query,page,country,device,date,searchAppearance)
• search_type (web,image,video,news,discover,googleNews, default web)
• query_filter, page_filter (contiene), country (ISO), device (DESKTOP/MOBILE/TABLET)
• row_limit (max 1000) Risposta: rows[] con keys[] + clicks/impressions/ctr/position. Senza dimensions, resta il bundle predefinito (totali + top query + top pagine).

Analytics (GA4) — metriche/dimensioni flessibili

GET /api/seo/analytics?property=… accetta ora (modalità custom):

• metrics (CSV, whitelist: sessions,activeUsers,newUsers,totalUsers,screenPageViews,engagementRate,averageSessionDuration,bounceRate,eventCount,conversions,…)
• dimensions (CSV, whitelist: pagePath,pageTitle,landingPage,country,city,region,deviceCategory,browser,operatingSystem,sessionSource,sessionMedium,sessionSourceMedium,date,language)
• order_by (una delle metrics), limit (max 1000) Senza metrics, resta il bundle predefinito.

Alert su canali

Gli alert generati (rank drop, spider 5xx, SSL in scadenza, blocco crawler AI, ecc.) vengono ora inviati anche ai canali configurati dall'utente (webhook, Slack, Discord, Telegram, …) tramite i Notification Handler del sistema, oltre all'email.