{ "openapi": "3.1.0", "info": { "title": "MarketingTracer API", "version": "1", "description": "Read your MarketingTracer data. The same endpoints power the app and the MCP server. Every call is a POST with a JSON body; GET with the same arguments in the query string also works for reading." }, "servers": [ { "url": "https://app.marketingtracer.com" } ], "security": [ { "bearer": [] } ], "paths": { "/rest/v1/linkbuilding.overview": { "post": { "operationId": "linkbuilding_overview", "tags": [ "linkbuilding" ], "summary": "Returns the link building results of one site: live and lost links, links won and lost per month (12 months up to month), how far the prospects added in the last 90 days got (found, contacted, agreed, live), what needs attention, and the anchor texts of the live links.", "description": "Returns the link building results of one site: live and lost links, links won and lost per month (12 months up to month), how far the prospects added in the last 90 days got (found, contacted, agreed, live), what needs attention, and the anchor texts of the live links.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "type": "string", "description": "The site: its id from list_sites, or the id in the app’s address." }, "month": { "type": "string", "pattern": "^\\d{4}-\\d{2}$", "description": "Last month of the 12-month series, YYYY-MM. Defaults to this month." } }, "required": [ "site_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "month": { "description": "The last month of the series, YYYY-MM.", "type": "string" }, "kpis": { "description": "The state now.", "type": "object", "properties": { "live": { "description": "Live links.", "type": "integer" }, "lost": { "description": "Links that were live and are gone.", "type": "integer" }, "waiting": { "description": "Contacted links waiting for an answer.", "type": "integer" }, "follow": { "description": "Checked live links that are follow (as last found).", "type": "integer" }, "checked": { "description": "Live links our check has found on their page at least once.", "type": "integer" }, "nofollow": { "description": "Checked live links that are nofollow (as last found).", "type": "integer" }, "new_this_month": { "description": "Links that went live in month.", "type": "integer" }, "lost_this_month": { "description": "Links lost in month.", "type": "integer" }, "follow_pct": { "description": "follow as a share of checked, 0-100, a whole number; null when no live link has been found yet.", "type": [ "number", "null" ] } }, "required": [ "live", "lost", "waiting", "follow", "checked", "nofollow", "new_this_month", "lost_this_month", "follow_pct" ] }, "months": { "description": "12 months up to month, oldest first.", "type": "array", "items": { "type": "object", "properties": { "month": { "description": "YYYY-MM.", "type": "string" }, "new": { "description": "Links that went live that month (for older links without a live date: the month they were added).", "type": "integer" }, "lost": { "description": "Links lost that month.", "type": "integer" } }, "required": [ "month", "new", "lost" ] } }, "funnel_90_days": { "description": "Prospects added in the last 90 days, by how far they got.", "type": "object", "properties": { "found": { "description": "All of them.", "type": "integer" }, "sent": { "description": "Contacted, or rejected later.", "type": "integer" }, "agreed": { "description": "Agreed (or further).", "type": "integer" }, "live": { "description": "Live (or lost later).", "type": "integer" } }, "required": [ "found", "sent", "agreed", "live" ] }, "attention": { "description": "What needs a look; the lists hold at most 5 each.", "type": "object", "properties": { "lost": { "description": "Links lost in the last 30 days.", "type": "array", "items": { "type": "object", "properties": { "link_id": { "description": "The link.", "type": "string" }, "url": { "description": "The page.", "type": "string" }, "lost_at": { "description": "When it was lost, ISO 8601 UTC.", "type": [ "string", "null" ] } }, "required": [ "link_id", "url", "lost_at" ] } }, "agreed_old": { "description": "Links agreed more than 14 days ago and not live yet.", "type": "array", "items": { "type": "object", "properties": { "link_id": { "description": "The link.", "type": "string" }, "url": { "description": "The page.", "type": "string" } }, "required": [ "link_id", "url" ] } }, "changed": { "description": "Live links that changed.", "type": "array", "items": { "type": "object", "properties": { "link_id": { "description": "The link.", "type": "string" }, "url": { "description": "The page.", "type": "string" }, "changes": { "description": "nofollow, anchor and/or target.", "type": "array", "items": { "type": "string" } } }, "required": [ "link_id", "url", "changes" ] } }, "mails_next_24h": { "description": "Outreach mails due within the next 24 hours, including overdue ones.", "type": "integer" } }, "required": [ "lost", "agreed_old", "changed", "mails_next_24h" ] }, "anchors": { "description": "The 4 most used anchor texts of the live links, then one row with anchor null for all the others.", "type": "array", "items": { "type": "object", "properties": { "anchor": { "description": "The anchor text, lowercase (the one our check found, else the one you want); null for the row with all other anchors.", "type": [ "string", "null" ] }, "count": { "description": "Live links with it.", "type": "integer" }, "share_pct": { "description": "Share of the live links that have an anchor text, 0-100, a whole number.", "type": "number" } }, "required": [ "anchor", "count", "share_pct" ] } }, "smtp_ready": { "description": "Whether the site's own mail server is set up and approved for outreach.", "type": "boolean" } }, "required": [ "month", "kpis", "months", "funnel_90_days", "attention", "anchors", "smtp_ready" ] }, "meta": { "type": "object", "description": "site_id; next_cursor and total for a list; period {from, to, compare_from, compare_to} where the endpoint covers a period." } }, "required": [ "data", "meta" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/rest/v1/linkbuilding.links": { "post": { "operationId": "linkbuilding_links", "tags": [ "linkbuilding" ], "summary": "Returns the links and prospects of one site, newest first: the page, its domain, the stage (found, sent = contacted, agreed, live, lost, rejected), the contact found, what our own check last saw on the page (is the link there, the anchor, follow or nofollow) and the state of the outreach mails.", "description": "Returns the links and prospects of one site, newest first: the page, its domain, the stage (found, sent = contacted, agreed, live, lost, rejected), the contact found, what our own check last saw on the page (is the link there, the anchor, follow or nofollow) and the state of the outreach mails.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "type": "string", "description": "The site: its id from list_sites, or the id in the app’s address." }, "stage": { "type": "string", "enum": [ "found", "sent", "agreed", "live", "lost", "rejected" ], "description": "Only links in this stage." }, "limit": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 100, "description": "Links per call." }, "cursor": { "type": "string", "description": "meta.next_cursor of the previous call, for the next page." } }, "required": [ "site_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "description": "The link id.", "type": "string" }, "url": { "description": "The page that links, or should link, to the site.", "type": "string" }, "domain": { "description": "Its domain.", "type": "string" }, "status": { "description": "The detailed status: open, pending, firstreminder, secondreminder, agreed, done, lost, rejected or stalled.", "type": "string" }, "stage": { "description": "found, sent, agreed, live, lost or rejected.", "type": "string" }, "my_url": { "description": "The page of the site the link should point to, as entered; null when not set (then the homepage).", "type": [ "string", "null" ] }, "anchor": { "description": "The anchor text you want.", "type": [ "string", "null" ] }, "tag": { "description": "Your own label.", "type": [ "string", "null" ] }, "note": { "description": "Your own note.", "type": [ "string", "null" ] }, "email": { "description": "The contact address found on this domain.", "type": [ "string", "null" ] }, "contact_form": { "description": "The contact form found on this domain.", "type": [ "string", "null" ] }, "contact_queued": { "description": "Whether a contact search is waiting.", "type": "boolean" }, "contact_checked_at": { "description": "When a contact was last looked for on this domain, ISO 8601 UTC.", "type": [ "string", "null" ] }, "added_at": { "description": "When it was added, ISO 8601 UTC.", "type": "string" }, "status_at": { "description": "When the status last changed, ISO 8601 UTC.", "type": [ "string", "null" ] }, "live_at": { "description": "When it went live, ISO 8601 UTC.", "type": [ "string", "null" ] }, "check": { "description": "Our check of the page.", "type": "object", "properties": { "state": { "description": "found, changed or missing at the last check that got an answer; null before that.", "type": [ "string", "null" ] }, "last_at": { "description": "When it was last checked, ISO 8601 UTC.", "type": [ "string", "null" ] }, "next_at": { "description": "When it is checked next, ISO 8601 UTC; null when it is not checked (stage found or rejected).", "type": [ "string", "null" ] }, "found": { "description": "The link as our check last found it on the page; null if never found.", "type": [ "object", "null" ], "properties": { "href": { "description": "Where it points.", "type": [ "string", "null" ] }, "anchor": { "description": "Its anchor text.", "type": [ "string", "null" ] }, "rel": { "description": "Its rel attribute.", "type": [ "string", "null" ] }, "follow": { "description": "Whether it is follow.", "type": "boolean" } }, "required": [ "href", "anchor", "rel", "follow" ] }, "history": { "description": "The last checks, oldest first, at most 12.", "type": "array", "items": { "type": "object", "properties": { "at": { "description": "When, ISO 8601 UTC.", "type": [ "string", "null" ] }, "result": { "description": "found, changed, missing, or error (the page did not answer; never counts as missing).", "type": [ "string", "null" ] } }, "required": [ "at", "result" ] } }, "changes": { "description": "What changed at the last check that found the link: nofollow, anchor and/or target.", "type": "array", "items": { "type": "string" } } }, "required": [ "state", "last_at", "next_at", "found", "history", "changes" ] }, "mail": { "description": "The outreach for this link.", "type": "object", "properties": { "sequence_id": { "description": "The sequence it is in.", "type": [ "string", "null" ] }, "step": { "description": "Mails sent so far.", "type": "integer" }, "next_at": { "description": "When the next mail goes out, ISO 8601 UTC.", "type": [ "string", "null" ] }, "last_at": { "description": "When the last mail went out, ISO 8601 UTC.", "type": [ "string", "null" ] }, "stopped": { "description": "Why the sequence stopped: manual, deleted (sequence removed), status (status changed), no_email, blocked (do-not-contact list), recent (domain contacted in the last 180 days) or no_step; null when it did not stop.", "type": [ "string", "null" ] }, "error": { "description": "The last sending error.", "type": [ "string", "null" ] } }, "required": [ "sequence_id", "step", "next_at", "last_at", "stopped", "error" ] } }, "required": [ "id", "url", "domain", "status", "stage", "my_url", "anchor", "tag", "note", "email", "contact_form", "contact_queued", "contact_checked_at", "added_at", "status_at", "live_at", "check", "mail" ] } }, "meta": { "type": "object", "description": "site_id; next_cursor and total for a list; period {from, to, compare_from, compare_to} where the endpoint covers a period." } }, "required": [ "data", "meta" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/rest/v1/linkbuilding.sequences": { "post": { "operationId": "linkbuilding_sequences", "tags": [ "linkbuilding" ], "summary": "Returns the outreach sequences of one site: a first mail and up to two follow-ups after a number of working days, with how many sites were contacted with it and how many agreed.", "description": "Returns the outreach sequences of one site: a first mail and up to two follow-ups after a number of working days, with how many sites were contacted with it and how many agreed.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "type": "string", "description": "The site: its id from list_sites, or the id in the app’s address." } }, "required": [ "site_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "description": "The sequence id.", "type": "string" }, "name": { "description": "Its name.", "type": "string" }, "steps": { "description": "The mails, in order.", "type": "array", "items": { "type": "object", "properties": { "subject": { "description": "The subject; empty for a follow-up means \"Re:\" plus the first subject.", "type": "string" }, "body": { "description": "The text, with the fields [partner_domain], [partner_link], [voornaam], [mijn_pagina] and [ankertekst].", "type": "string" }, "after_workdays": { "description": "Working days after the mail before; always 0 for the first.", "type": "integer" } }, "required": [ "subject", "body", "after_workdays" ] } }, "contacted": { "description": "Links that got at least one mail of it.", "type": "integer" }, "agreed": { "description": "Links in it that are now agreed or live.", "type": "integer" } }, "required": [ "id", "name", "steps", "contacted", "agreed" ] } }, "meta": { "type": "object", "description": "site_id; next_cursor and total for a list; period {from, to, compare_from, compare_to} where the endpoint covers a period." } }, "required": [ "data", "meta" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/rest/v1/linkbuilding.queue": { "post": { "operationId": "linkbuilding_queue", "tags": [ "linkbuilding" ], "summary": "Returns the outreach mails scheduled for one site, sent through the site's own mail server on working days, and how many went out today against the daily limit.", "description": "Returns the outreach mails scheduled for one site, sent through the site's own mail server on working days, and how many went out today against the daily limit.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "type": "string", "description": "The site: its id from list_sites, or the id in the app’s address." } }, "required": [ "site_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "sent_today": { "description": "Mails sent today (Amsterdam time).", "type": "integer" }, "day_limit": { "description": "Mails the site sends at most per day.", "type": "integer" }, "scheduled": { "description": "The next mails, soonest first, at most 100, including overdue ones.", "type": "array", "items": { "type": "object", "properties": { "link_id": { "description": "The link.", "type": "string" }, "domain": { "description": "The site it goes to.", "type": "string" }, "email": { "description": "The address.", "type": [ "string", "null" ] }, "sequence_id": { "description": "The sequence.", "type": [ "string", "null" ] }, "sequence": { "description": "Its name.", "type": [ "string", "null" ] }, "step": { "description": "Mails sent so far; this is the next one.", "type": "integer" }, "send_at": { "description": "When it goes out, ISO 8601 UTC; the time may already have passed.", "type": [ "string", "null" ] }, "error": { "description": "The last sending error.", "type": [ "string", "null" ] } }, "required": [ "link_id", "domain", "email", "sequence_id", "sequence", "step", "send_at", "error" ] } } }, "required": [ "sent_today", "day_limit", "scheduled" ] }, "meta": { "type": "object", "description": "site_id; next_cursor and total for a list; period {from, to, compare_from, compare_to} where the endpoint covers a period." } }, "required": [ "data", "meta" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/rest/v1/serp.summary": { "post": { "operationId": "serp_summary", "tags": [ "serp" ], "summary": "Returns the Rank tracker status of one site: whether measuring is on, whether the site is in its trial, how deep each measurement goes, the months with data, how many keywords are in use of the site's quota, and when the latest and the next measurement are.", "description": "Returns the Rank tracker status of one site: whether measuring is on, whether the site is in its trial, how deep each measurement goes, the months with data, how many keywords are in use of the site's quota, and when the latest and the next measurement are. Positions are real Google results per keyword, country and device, separate from Search Console.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "type": "string", "description": "The site: its id from list_sites, or the id in the app’s address." }, "month": { "type": "string", "pattern": "^\\d{4}-\\d{2}$", "description": "Last month to show, YYYY-MM, for a report of an earlier month. Defaults to this month." } }, "required": [ "site_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "measuring_enabled": { "description": "Whether the Rank tracker is measuring at all right now (one switch for all sites).", "type": "boolean" }, "trial": { "description": "Whether the site is in its free trial. The Rank tracker does not measure during the trial.", "type": "boolean" }, "own_domain": { "description": "The domain of the site, without www.", "type": "string" }, "depth": { "description": "How deep each measurement goes: 20 means the top 20. A position below that is null.", "type": "integer" }, "months": { "description": "The months serp.keywords returns, YYYY-MM, oldest first: the six months before this month (or before month), plus that month itself once it has a measurement.", "type": "array", "items": { "type": "string" } }, "report_month": { "description": "The month asked for with month; null when month was not given.", "type": [ "string", "null" ] }, "quota": { "description": "Keywords this calendar month.", "type": "object", "properties": { "used": { "description": "Keywords (keyword, country and device) measured or queued this calendar month, including ones deleted since; deleting a keyword does not give its slot back.", "type": "integer" }, "total": { "description": "Keywords the site's plan allows.", "type": "integer" } }, "required": [ "used", "total" ] }, "last_measured_at": { "description": "When the site's newest measurement of any keyword came in, ISO 8601 UTC; null before the first one. Not limited by month.", "type": [ "string", "null" ] }, "next_measurement_at": { "description": "When the next scheduled measurement starts, ISO 8601 UTC; null for a report of an earlier month.", "type": [ "string", "null" ] }, "can_set_plan": { "description": "Whether the caller may set a measuring plan for the site (white label admins).", "type": "boolean" }, "can_buy": { "description": "Whether the caller may buy a bigger plan for the site.", "type": "boolean" } }, "required": [ "measuring_enabled", "trial", "own_domain", "depth", "months", "report_month", "quota", "last_measured_at", "next_measurement_at", "can_set_plan", "can_buy" ] }, "meta": { "type": "object", "description": "site_id; next_cursor and total for a list; period {from, to, compare_from, compare_to} where the endpoint covers a period." } }, "required": [ "data", "meta" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/rest/v1/serp.keywords": { "post": { "operationId": "serp_keywords", "tags": [ "serp" ], "summary": "Returns the tracked keywords of one site, oldest first, one item per keyword, country and device: the site's best position in the latest measured month and in the measured month before, the change, the position per month, the position per month of each own page that ranked and of each followed competitor, plus the monthly search volume.", "description": "Returns the tracked keywords of one site, oldest first, one item per keyword, country and device: the site's best position in the latest measured month and in the measured month before, the change, the position per month, the position per month of each own page that ranked and of each followed competitor, plus the monthly search volume. A position is null when the site was not in the measured top, or when nothing was measured that month (measured false).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "type": "string", "description": "The site: its id from list_sites, or the id in the app’s address." }, "month": { "type": "string", "pattern": "^\\d{4}-\\d{2}$", "description": "Last month of the series, YYYY-MM, for a report of an earlier month. Defaults to this month." }, "group": { "type": "string", "maxLength": 40, "description": "Only the keywords in this group." }, "limit": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1000, "description": "Keywords per call." }, "cursor": { "type": "string", "description": "meta.next_cursor of the previous call, for the next page." } }, "required": [ "site_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "description": "The keyword id; keyword_id in serp.keyword.", "type": "string" }, "keyword": { "description": "The keyword as tracked.", "type": "string" }, "country": { "description": "Two-letter country code of the Google that is measured, e.g. nl.", "type": "string" }, "device": { "description": "desktop or mobile.", "type": "string" }, "group": { "description": "The group the keyword is in; null without a group.", "type": [ "string", "null" ] }, "starred": { "description": "Whether the keyword has a star.", "type": "boolean" }, "target_url": { "description": "The page that should rank for this keyword; null when not set.", "type": [ "string", "null" ] }, "search_volume": { "description": "Average searches per month in this country; null when not known yet.", "type": [ "integer", "null" ] }, "state": { "description": "new (waiting for its first measurement), queued, ok or error.", "type": "string" }, "paused": { "description": "Whether the keyword falls outside the plan's keyword count and is not measured (starred keywords count first, then the oldest).", "type": "boolean" }, "last_measured_month": { "description": "The latest month in the series with a measurement, YYYY-MM; null when no month has one.", "type": [ "string", "null" ] }, "position": { "description": "The site's best position at the last measurement of last_measured_month; null when not in the measured top or without a measurement.", "type": [ "integer", "null" ] }, "previous_position": { "description": "The site's best position in the measured month before last_measured_month (its last measurement that month); null when not in the top or without such a month.", "type": [ "integer", "null" ] }, "change": { "description": "Places gained between the last two measured months (positive is up); a month outside the measured top counts as depth + 1. Null with fewer than two measured months.", "type": [ "integer", "null" ] }, "positions": { "description": "The best position of the site per month, oldest first.", "type": "array", "items": { "type": "object", "properties": { "month": { "description": "YYYY-MM.", "type": "string" }, "position": { "description": "The best position that month; null when not in the top or not measured.", "type": [ "integer", "null" ] }, "measured": { "description": "Whether the keyword was measured that month.", "type": "boolean" } }, "required": [ "month", "position", "measured" ] } }, "pages": { "description": "Each own page that ranked for the keyword, with its position per month.", "type": "array", "items": { "type": "object", "properties": { "url": { "description": "The page.", "type": "string" }, "positions": { "description": "Per month, oldest first.", "type": "array", "items": { "type": "object", "properties": { "month": { "description": "YYYY-MM.", "type": "string" }, "position": { "description": "The position of this page; null when not in the measured top or not measured that month.", "type": [ "integer", "null" ] } }, "required": [ "month", "position" ] } } }, "required": [ "url", "positions" ] } }, "competitors": { "description": "Each followed competitor (also when it never ranked), with its best position per month.", "type": "array", "items": { "type": "object", "properties": { "domain": { "description": "The competitor.", "type": "string" }, "positions": { "description": "Per month, oldest first.", "type": "array", "items": { "type": "object", "properties": { "month": { "description": "YYYY-MM.", "type": "string" }, "position": { "description": "The best position of this domain; null when not in the measured top or not measured that month.", "type": [ "integer", "null" ] } }, "required": [ "month", "position" ] } } }, "required": [ "domain", "positions" ] } } }, "required": [ "id", "keyword", "country", "device", "group", "starred", "target_url", "search_volume", "state", "paused", "last_measured_month", "position", "previous_position", "change", "positions", "pages", "competitors" ] } }, "meta": { "type": "object", "description": "site_id; next_cursor and total for a list; period {from, to, compare_from, compare_to} where the endpoint covers a period." } }, "required": [ "data", "meta" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/rest/v1/serp.keyword": { "post": { "operationId": "serp_keyword", "tags": [ "serp" ], "summary": "Returns one tracked keyword up close: the organic top of its latest measurement (every result with its position, domain, URL and whether it is the site's own page), and the position per month of every other domain in that top, of each followed competitor and of each own page.", "description": "Returns one tracked keyword up close: the organic top of its latest measurement (every result with its position, domain, URL and whether it is the site's own page), and the position per month of every other domain in that top, of each followed competitor and of each own page.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "type": "string", "description": "The site: its id from list_sites, or the id in the app’s address." }, "keyword_id": { "type": "string", "description": "The id from serp.keywords." } }, "required": [ "site_id", "keyword_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "description": "The keyword id.", "type": "string" }, "keyword": { "description": "The keyword.", "type": "string" }, "country": { "description": "Two-letter country code.", "type": "string" }, "device": { "description": "desktop or mobile.", "type": "string" }, "measured_at": { "description": "When the latest measurement came in, ISO 8601 UTC; null before the first one (top is then empty).", "type": [ "string", "null" ] }, "months": { "description": "The six months before this month, plus this month once it has a measurement, oldest first.", "type": "array", "items": { "type": "object", "properties": { "month": { "description": "YYYY-MM.", "type": "string" }, "measured": { "description": "Whether the keyword was measured that month.", "type": "boolean" } }, "required": [ "month", "measured" ] } }, "top": { "description": "The organic results of the latest measurement, best first.", "type": "array", "items": { "type": "object", "properties": { "position": { "description": "The organic position in Google.", "type": "integer" }, "domain": { "description": "The domain, without www.", "type": "string" }, "url": { "description": "The page.", "type": "string" }, "own": { "description": "Whether it is a page of the site itself.", "type": "boolean" } }, "required": [ "position", "domain", "url", "own" ] } }, "pages": { "description": "Each own page that ranked, with its position per month.", "type": "array", "items": { "type": "object", "properties": { "url": { "description": "The page.", "type": "string" }, "positions": { "description": "Per month, oldest first.", "type": "array", "items": { "type": "object", "properties": { "month": { "description": "YYYY-MM.", "type": "string" }, "position": { "description": "The position of this page; null when not in the measured top or not measured that month.", "type": [ "integer", "null" ] } }, "required": [ "month", "position" ] } } }, "required": [ "url", "positions" ] } }, "domains": { "description": "Each other domain in the latest top, plus each followed competitor, with its best position per month.", "type": "array", "items": { "type": "object", "properties": { "domain": { "description": "The domain.", "type": "string" }, "positions": { "description": "Per month, oldest first.", "type": "array", "items": { "type": "object", "properties": { "month": { "description": "YYYY-MM.", "type": "string" }, "position": { "description": "The best position of this domain; null when not in the measured top or not measured that month.", "type": [ "integer", "null" ] } }, "required": [ "month", "position" ] } } }, "required": [ "domain", "positions" ] } } }, "required": [ "id", "keyword", "country", "device", "measured_at", "months", "top", "pages", "domains" ] }, "meta": { "type": "object", "description": "site_id; next_cursor and total for a list; period {from, to, compare_from, compare_to} where the endpoint covers a period." } }, "required": [ "data", "meta" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/rest/v1/serp.competitors": { "post": { "operationId": "serp_competitors", "tags": [ "serp" ], "summary": "Returns the followed competitors of one site (one list shared by the Rank tracker, Core Web Vitals and AI Insights), and suggestions: the domains that show up most often in the latest tops of the site's tracked keywords.", "description": "Returns the followed competitors of one site (one list shared by the Rank tracker, Core Web Vitals and AI Insights), and suggestions: the domains that show up most often in the latest tops of the site's tracked keywords.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "type": "string", "description": "The site: its id from list_sites, or the id in the app’s address." } }, "required": [ "site_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "competitors": { "description": "The followed competitors, at most 6 domains.", "type": "array", "items": { "type": "string" } }, "suggestions": { "description": "At most 6 domains, other than the site and its followed competitors, that are most often in the latest tops of the tracked keywords, most first.", "type": "array", "items": { "type": "object", "properties": { "domain": { "description": "The domain.", "type": "string" }, "keywords": { "description": "For how many tracked keywords it is in the latest top (once per keyword).", "type": "integer" } }, "required": [ "domain", "keywords" ] } } }, "required": [ "competitors", "suggestions" ] }, "meta": { "type": "object", "description": "site_id; next_cursor and total for a list; period {from, to, compare_from, compare_to} where the endpoint covers a period." } }, "required": [ "data", "meta" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/rest/v1/aiinsights.summary": { "post": { "operationId": "aiinsights_summary", "tags": [ "aiinsights" ], "summary": "Returns the AI visibility of one site: of the current answers (per prompt and AI the latest answer, if it is at most 62 days old), how many mention the site (name it or link to it) and how many link to it (cite one of its pages as a source), as a share now against the last day of the previous period, also per AI (ChatGPT, Gemini); plus the prompts, the measuring package and what is connected.", "description": "Returns the AI visibility of one site: of the current answers (per prompt and AI the latest answer, if it is at most 62 days old), how many mention the site (name it or link to it) and how many link to it (cite one of its pages as a source), as a share now against the last day of the previous period, also per AI (ChatGPT, Gemini); plus the prompts, the measuring package and what is connected. One measurement is one prompt asked to one AI; one round asks every prompt once, at the package's frequency.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "type": "string", "description": "The site: its id from list_sites, or the id in the app’s address." }, "from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "First day of the period, YYYY-MM-DD; give it together with to. Without from and to, the period is the last 28 days up to yesterday, against the 28 days before." }, "to": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Last day of the period, YYYY-MM-DD (at most yesterday); give it together with from. The previous period is then the same days one month earlier." } }, "required": [ "site_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "prompts": { "description": "Prompts of the site.", "type": "integer" }, "prompts_measured": { "description": "Prompts with at least one current answer.", "type": "integer" }, "last_measured_date": { "description": "The day of the site's newest answer, YYYY-MM-DD; null before the first answer.", "type": [ "string", "null" ] }, "engines": { "description": "The AIs the prompts are asked to.", "type": "array", "items": { "type": "object", "properties": { "key": { "description": "chatgpt or gemini.", "type": "string" }, "label": { "description": "The name to show.", "type": "string" } }, "required": [ "key", "label" ] } }, "answers": { "description": "Current answers: per prompt and AI the latest answer, if it is at most 62 days old.", "type": "integer" }, "mentioned": { "description": "Current answers that mention the site (name it or link to it).", "type": "integer" }, "linked": { "description": "Current answers that link to the site (cite one of its pages as a source).", "type": "integer" }, "mentioned_pct": { "description": "The share of current answers that mention the site, 0-100, on the last day of the period, against the last day of the previous period.", "type": "object", "properties": { "value": { "description": "Now (or on to); null without answers.", "type": [ "number", "null" ] }, "previous": { "description": "The previous period; null when there was nothing to compare with.", "type": [ "number", "null" ] }, "change": { "description": "value minus previous (for a _pct field: percentage points).", "type": [ "number", "null" ] }, "change_pct": { "description": "The change in percent of previous; null when previous is 0 or null.", "type": [ "number", "null" ] } }, "required": [ "value", "previous", "change", "change_pct" ] }, "linked_pct": { "description": "The share of current answers that link to the site, 0-100, on the last day of the period, against the last day of the previous period.", "type": "object", "properties": { "value": { "description": "Now (or on to); null without answers.", "type": [ "number", "null" ] }, "previous": { "description": "The previous period; null when there was nothing to compare with.", "type": [ "number", "null" ] }, "change": { "description": "value minus previous (for a _pct field: percentage points).", "type": [ "number", "null" ] }, "change_pct": { "description": "The change in percent of previous; null when previous is 0 or null.", "type": [ "number", "null" ] } }, "required": [ "value", "previous", "change", "change_pct" ] }, "per_engine": { "description": "The same counts per AI.", "type": "array", "items": { "type": "object", "properties": { "key": { "description": "chatgpt or gemini.", "type": "string" }, "label": { "description": "The name to show.", "type": "string" }, "answers": { "description": "Current answers of this AI.", "type": "integer" }, "mentioned": { "description": "Answers that mention the site.", "type": "integer" }, "linked": { "description": "Answers that link to the site.", "type": "integer" } }, "required": [ "key", "label", "answers", "mentioned", "linked" ] } }, "brand_terms": { "description": "The names we look for in the answers.", "type": "array", "items": { "type": "string" } }, "competitors": { "description": "The followed competitors (the list shared with the Rank tracker).", "type": "array", "items": { "type": "string" } }, "ga4_connected": { "description": "Whether GA4 is connected; the traffic endpoints need it.", "type": "boolean" }, "search_console_connected": { "description": "Whether Search Console is connected.", "type": "boolean" }, "rank_tracker_keywords": { "description": "Tracked keywords in the Rank tracker; aiinsights.ai_overviews needs them.", "type": "integer" }, "package": { "description": "The measuring package of the site.", "type": "object", "properties": { "frequency": { "description": "monthly, biweekly or weekly: how often a round runs.", "type": "string" }, "measurements": { "description": "Measurements per round.", "type": "integer" } }, "required": [ "frequency", "measurements" ] }, "included": { "description": "The package that comes with every site.", "type": "object", "properties": { "frequency": { "description": "monthly, biweekly or weekly: how often a round runs.", "type": "string" }, "measurements": { "description": "Measurements per round.", "type": "integer" } }, "required": [ "frequency", "measurements" ] }, "measurements_used": { "description": "Measurements the prompts take per round; above the package, the newest prompts are paused.", "type": "integer" }, "can_write": { "description": "Whether the caller may add and change prompts.", "type": "boolean" }, "can_set_plan": { "description": "Whether the caller may set a package for the site (white label admins).", "type": "boolean" }, "can_buy": { "description": "Whether the caller may buy a bigger package.", "type": "boolean" } }, "required": [ "prompts", "prompts_measured", "last_measured_date", "engines", "answers", "mentioned", "linked", "mentioned_pct", "linked_pct", "per_engine", "brand_terms", "competitors", "ga4_connected", "search_console_connected", "rank_tracker_keywords", "package", "included", "measurements_used", "can_write", "can_set_plan", "can_buy" ] }, "meta": { "type": "object", "description": "site_id; next_cursor and total for a list; period {from, to, compare_from, compare_to} where the endpoint covers a period." } }, "required": [ "data", "meta" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/rest/v1/aiinsights.prompts": { "post": { "operationId": "aiinsights_prompts", "tags": [ "aiinsights" ], "summary": "Returns the prompts of one site, oldest first, with per AI the status of the current answer (linked: the site is a source; mentioned: named, not linked; none: not named; nosearch: the AI did not search the web and did not name the site; null: no answer from the last 62 days), the site's place among the sources, the other sites that appear in the answers, and the best status per week over the last 12 weeks.", "description": "Returns the prompts of one site, oldest first, with per AI the status of the current answer (linked: the site is a source; mentioned: named, not linked; none: not named; nosearch: the AI did not search the web and did not name the site; null: no answer from the last 62 days), the site's place among the sources, the other sites that appear in the answers, and the best status per week over the last 12 weeks.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "type": "string", "description": "The site: its id from list_sites, or the id in the app’s address." } }, "required": [ "site_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "description": "The prompt id; prompt_id in aiinsights.prompt.", "type": "string" }, "prompt": { "description": "The question as asked.", "type": "string" }, "engines": { "description": "The AIs this prompt is asked to.", "type": "array", "items": { "type": "string" } }, "brand_terms": { "description": "Extra names looked for in the answers to this prompt.", "type": "array", "items": { "type": "string" } }, "paused": { "description": "Whether the prompt is above the package and not asked.", "type": "boolean" }, "errors": { "description": "Keys of the AIs (chatgpt, gemini) whose latest attempt failed.", "type": "array", "items": { "type": "string" } }, "created_at": { "description": "When the prompt was added, ISO 8601 UTC.", "type": [ "string", "null" ] }, "per_engine": { "description": "The latest answer per AI.", "type": "array", "items": { "type": "object", "properties": { "key": { "description": "chatgpt or gemini.", "type": "string" }, "label": { "description": "The name to show.", "type": "string" }, "asked": { "description": "Whether this prompt is asked to this AI.", "type": "boolean" }, "status": { "description": "linked, mentioned, none or nosearch for the current answer; null when there is no answer from the last 62 days.", "type": [ "string", "null" ] }, "position": { "description": "The site's first place among the answer's sources; null when the answer does not link to the site.", "type": [ "integer", "null" ] }, "date": { "description": "The day of the answer, YYYY-MM-DD; null without a current answer.", "type": [ "string", "null" ] } }, "required": [ "key", "label", "asked", "status", "position", "date" ] } }, "also_mentioned": { "description": "The other domains that appear most often in the current answers (cited or named), at most 3.", "type": "array", "items": { "type": "string" } }, "weeks": { "description": "The best status over the AIs per week, oldest first, 12 weeks.", "type": "array", "items": { "type": "object", "properties": { "date": { "description": "The Monday of the week, YYYY-MM-DD.", "type": "string" }, "status": { "description": "linked, mentioned, none, nosearch, or null without an answer that week.", "type": [ "string", "null" ] } }, "required": [ "date", "status" ] } } }, "required": [ "id", "prompt", "engines", "brand_terms", "paused", "errors", "created_at", "per_engine", "also_mentioned", "weeks" ] } }, "meta": { "type": "object", "description": "site_id; next_cursor and total for a list; period {from, to, compare_from, compare_to} where the endpoint covers a period." } }, "required": [ "data", "meta" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/rest/v1/aiinsights.prompt": { "post": { "operationId": "aiinsights_prompt", "tags": [ "aiinsights" ], "summary": "Returns one prompt up close: per AI its status per week over the last 12 weeks, and its latest answer with the text, the sources it cited (the site's own pages marked) and the other sites in it; plus the site's own pages the AIs cite, with their visits from AI over the last 28 days (GA4).", "description": "Returns one prompt up close: per AI its status per week over the last 12 weeks, and its latest answer with the text, the sources it cited (the site's own pages marked) and the other sites in it; plus the site's own pages the AIs cite, with their visits from AI over the last 28 days (GA4).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "type": "string", "description": "The site: its id from list_sites, or the id in the app’s address." }, "prompt_id": { "type": "string", "description": "The id from aiinsights.prompts." } }, "required": [ "site_id", "prompt_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "description": "The prompt id.", "type": "string" }, "prompt": { "description": "The question as asked.", "type": "string" }, "country": { "description": "Two-letter code of the country the prompt is asked for; null when not set.", "type": [ "string", "null" ] }, "language": { "description": "Two-letter language code; null when not set.", "type": [ "string", "null" ] }, "engines": { "description": "The AIs this prompt is asked to.", "type": "array", "items": { "type": "string" } }, "brand_terms": { "description": "Extra names looked for in the answers to this prompt.", "type": "array", "items": { "type": "string" } }, "created_at": { "description": "When the prompt was added, ISO 8601 UTC.", "type": [ "string", "null" ] }, "per_engine": { "description": "Per AI.", "type": "array", "items": { "type": "object", "properties": { "key": { "description": "chatgpt or gemini.", "type": "string" }, "label": { "description": "The name to show.", "type": "string" }, "weeks": { "description": "12 weeks, oldest first.", "type": "array", "items": { "type": "object", "properties": { "date": { "description": "The Monday of the week, YYYY-MM-DD.", "type": "string" }, "status": { "description": "linked, mentioned, none or nosearch; null without an answer that week.", "type": [ "string", "null" ] }, "position": { "description": "The site's first place among the sources; null when that answer does not link to the site.", "type": [ "integer", "null" ] } }, "required": [ "date", "status", "position" ] } }, "answer": { "description": "The current answer (the latest, at most 62 days old); null when there is none.", "type": [ "object", "null" ], "properties": { "date": { "description": "The day of the answer, YYYY-MM-DD.", "type": "string" }, "status": { "description": "linked, mentioned, none or nosearch.", "type": "string" }, "position": { "description": "The site's first place among the sources; null when the answer does not link to the site.", "type": [ "integer", "null" ] }, "text": { "description": "The answer as the AI gave it (usually Markdown), cut at 6,000 characters.", "type": "string" }, "sources": { "description": "The pages the answer cites, in order.", "type": "array", "items": { "type": "object", "properties": { "position": { "description": "The place among the sources.", "type": "integer" }, "url": { "description": "The page.", "type": "string" }, "domain": { "description": "Its domain.", "type": "string" }, "own": { "description": "Whether it is a page of the site itself.", "type": "boolean" } }, "required": [ "position", "url", "domain", "own" ] } }, "other_sites": { "description": "The other sites in the answer.", "type": "array", "items": { "type": "object", "properties": { "domain": { "description": "The domain.", "type": "string" }, "mentioned": { "description": "Whether the text names it.", "type": "boolean" }, "position": { "description": "Its first place among the sources; null when only named.", "type": [ "integer", "null" ] } }, "required": [ "domain", "mentioned", "position" ] } } }, "required": [ "date", "status", "position", "text", "sources", "other_sites" ] } }, "required": [ "key", "label", "weeks", "answer" ] } }, "own_pages": { "description": "The site's own pages the current answers cite.", "type": "array", "items": { "type": "object", "properties": { "url": { "description": "The page.", "type": "string" }, "path": { "description": "Its path.", "type": "string" }, "cited_by": { "description": "Which AI cites it, and where.", "type": "array", "items": { "type": "object", "properties": { "key": { "description": "chatgpt or gemini.", "type": "string" }, "position": { "description": "This page's place among that answer's sources.", "type": [ "integer", "null" ] } }, "required": [ "key", "position" ] } }, "ai_sessions": { "description": "Visits from AI assistants to this page, last 28 days; null without GA4.", "type": [ "integer", "null" ] }, "conversions": { "description": "Key events of those visits, last 28 days (GA4); null without GA4.", "type": [ "number", "null" ] }, "revenue_eur": { "description": "Revenue of those visits in euro, last 28 days (GA4); null without GA4.", "type": [ "number", "null" ] } }, "required": [ "url", "path", "cited_by", "ai_sessions", "conversions", "revenue_eur" ] } } }, "required": [ "id", "prompt", "country", "language", "engines", "brand_terms", "created_at", "per_engine", "own_pages" ] }, "meta": { "type": "object", "description": "site_id; next_cursor and total for a list; period {from, to, compare_from, compare_to} where the endpoint covers a period." } }, "required": [ "data", "meta" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/rest/v1/aiinsights.competitors": { "post": { "operationId": "aiinsights_competitors", "tags": [ "aiinsights" ], "summary": "Returns who appears in the current answers to the site's prompts (named or cited), against 28 days earlier: the site itself, the other sites (the 15 that appear most, plus every followed competitor), the pages of other sites the AIs cite most often, and the followed competitors.", "description": "Returns who appears in the current answers to the site's prompts (named or cited), against 28 days earlier: the site itself, the other sites (the 15 that appear most, plus every followed competitor), the pages of other sites the AIs cite most often, and the followed competitors.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "type": "string", "description": "The site: its id from list_sites, or the id in the app’s address." } }, "required": [ "site_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "answers": { "description": "Current answers (per prompt and AI the latest, at most 62 days old).", "type": "integer" }, "own": { "description": "The site itself.", "type": "object", "properties": { "domain": { "description": "The site's domain.", "type": "string" }, "answers": { "description": "The same as answers.", "type": "integer" }, "mentioned": { "description": "Current answers that mention the site.", "type": "integer" }, "linked": { "description": "Current answers that link to it.", "type": "integer" }, "mentioned_previous": { "description": "Answers that mentioned it 28 days earlier; null when there were no answers then.", "type": [ "integer", "null" ] }, "per_engine": { "description": "Mentions per AI.", "type": "array", "items": { "type": "object", "properties": { "key": { "description": "chatgpt or gemini.", "type": "string" }, "label": { "description": "The name to show.", "type": "string" }, "mentioned": { "description": "Answers that mention the site.", "type": "integer" } }, "required": [ "key", "label", "mentioned" ] } } }, "required": [ "domain", "answers", "mentioned", "linked", "mentioned_previous", "per_engine" ] }, "sites": { "description": "Other sites in the current answers (cited or named): the 15 that appear most, then every other followed competitor (with 0 when absent).", "type": "array", "items": { "type": "object", "properties": { "domain": { "description": "The domain.", "type": "string" }, "answers": { "description": "Answers it appears in (named or as a source).", "type": "integer" }, "mentioned": { "description": "Answers whose text names it.", "type": "integer" }, "linked": { "description": "Answers that cite it as a source.", "type": "integer" }, "answers_previous": { "description": "Answers it appeared in 28 days earlier; null when there were no answers then.", "type": [ "integer", "null" ] }, "followed": { "description": "Whether it is a followed competitor.", "type": "boolean" }, "per_engine": { "description": "Answers per AI.", "type": "array", "items": { "type": "object", "properties": { "key": { "description": "chatgpt or gemini.", "type": "string" }, "label": { "description": "The name to show.", "type": "string" }, "answers": { "description": "Answers it appears in.", "type": "integer" } }, "required": [ "key", "label", "answers" ] } } }, "required": [ "domain", "answers", "mentioned", "linked", "answers_previous", "followed", "per_engine" ] } }, "cited_pages": { "description": "Pages of other sites the AIs cite most, at most 8.", "type": "array", "items": { "type": "object", "properties": { "url": { "description": "The page.", "type": "string" }, "domain": { "description": "Its domain.", "type": "string" }, "citations": { "description": "In how many current answers it is a source.", "type": "integer" }, "prompts": { "description": "For how many prompts.", "type": "integer" } }, "required": [ "url", "domain", "citations", "prompts" ] } }, "competitors": { "description": "The followed competitors (the list shared with the Rank tracker).", "type": "array", "items": { "type": "string" } } }, "required": [ "answers", "own", "sites", "cited_pages", "competitors" ] }, "meta": { "type": "object", "description": "site_id; next_cursor and total for a list; period {from, to, compare_from, compare_to} where the endpoint covers a period." } }, "required": [ "data", "meta" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/rest/v1/aiinsights.traffic_summary": { "post": { "operationId": "aiinsights_traffic_summary", "tags": [ "aiinsights" ], "summary": "Returns the visits from AI assistants (ChatGPT, Perplexity, Gemini, Copilot, Claude and others) in Google Analytics 4 for the period: sessions, engaged sessions, key events and revenue against the previous period, the share of all visits, and the same per AI.", "description": "Returns the visits from AI assistants (ChatGPT, Perplexity, Gemini, Copilot, Claude and others) in Google Analytics 4 for the period: sessions, engaged sessions, key events and revenue against the previous period, the share of all visits, and the same per AI. Without GA4 data, ga4_connected is false, the figures are null and per_engine is empty.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "type": "string", "description": "The site: its id from list_sites, or the id in the app’s address." }, "from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "First day of the period, YYYY-MM-DD; give it together with to. Without from and to, the period is the last 28 days up to yesterday, against the 28 days before." }, "to": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Last day of the period, YYYY-MM-DD (at most yesterday); give it together with from. The previous period is then the same days one month earlier." } }, "required": [ "site_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ga4_connected": { "description": "Whether GA4 data came back (false when GA4 is not connected or did not answer).", "type": "boolean" }, "sessions": { "description": "Sessions from AI assistants in the period, against the previous period.", "type": [ "object", "null" ], "properties": { "value": { "description": "This period.", "type": [ "number", "null" ] }, "previous": { "description": "The previous period; null when there was nothing to compare with.", "type": [ "number", "null" ] }, "change": { "description": "value minus previous (for a _pct field: percentage points).", "type": [ "number", "null" ] }, "change_pct": { "description": "The change in percent of previous; null when previous is 0 or null.", "type": [ "number", "null" ] } }, "required": [ "value", "previous", "change", "change_pct" ] }, "engaged_sessions": { "description": "Engaged sessions from AI assistants in the period, against the previous period.", "type": [ "object", "null" ], "properties": { "value": { "description": "This period.", "type": [ "number", "null" ] }, "previous": { "description": "The previous period; null when there was nothing to compare with.", "type": [ "number", "null" ] }, "change": { "description": "value minus previous (for a _pct field: percentage points).", "type": [ "number", "null" ] }, "change_pct": { "description": "The change in percent of previous; null when previous is 0 or null.", "type": [ "number", "null" ] } }, "required": [ "value", "previous", "change", "change_pct" ] }, "conversions": { "description": "Key events of those sessions in the period, against the previous period.", "type": [ "object", "null" ], "properties": { "value": { "description": "This period.", "type": [ "number", "null" ] }, "previous": { "description": "The previous period; null when there was nothing to compare with.", "type": [ "number", "null" ] }, "change": { "description": "value minus previous (for a _pct field: percentage points).", "type": [ "number", "null" ] }, "change_pct": { "description": "The change in percent of previous; null when previous is 0 or null.", "type": [ "number", "null" ] } }, "required": [ "value", "previous", "change", "change_pct" ] }, "revenue_eur": { "description": "Revenue of those sessions in euro in the period, against the previous period.", "type": [ "object", "null" ], "properties": { "value": { "description": "This period.", "type": [ "number", "null" ] }, "previous": { "description": "The previous period; null when there was nothing to compare with.", "type": [ "number", "null" ] }, "change": { "description": "value minus previous (for a _pct field: percentage points).", "type": [ "number", "null" ] }, "change_pct": { "description": "The change in percent of previous; null when previous is 0 or null.", "type": [ "number", "null" ] } }, "required": [ "value", "previous", "change", "change_pct" ] }, "all_sessions": { "description": "All sessions of the site in the period.", "type": [ "integer", "null" ] }, "ai_share_pct": { "description": "Sessions from AI as a share of all sessions, 0-100.", "type": [ "number", "null" ] }, "per_engine": { "description": "Per AI, most sessions first.", "type": "array", "items": { "type": "object", "properties": { "key": { "description": "chatgpt, perplexity, gemini, copilot, claude, deepseek, meta, grok, mistral, you, phind or poe.", "type": "string" }, "label": { "description": "The name to show.", "type": "string" }, "sessions": { "description": "Sessions.", "type": "integer" }, "engaged_sessions": { "description": "Engaged sessions.", "type": "integer" }, "conversions": { "description": "Key events.", "type": "number" }, "revenue_eur": { "description": "Revenue in euro.", "type": "number" } }, "required": [ "key", "label", "sessions", "engaged_sessions", "conversions", "revenue_eur" ] } } }, "required": [ "ga4_connected", "sessions", "engaged_sessions", "conversions", "revenue_eur", "all_sessions", "ai_share_pct", "per_engine" ] }, "meta": { "type": "object", "description": "site_id; next_cursor and total for a list; period {from, to, compare_from, compare_to} where the endpoint covers a period." } }, "required": [ "data", "meta" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/rest/v1/aiinsights.traffic_pages": { "post": { "operationId": "aiinsights_traffic_pages", "tags": [ "aiinsights" ], "summary": "Returns the visits from AI assistants per landing page in the period (GA4), most first: per AI, engaged sessions, key events, revenue, the sessions in the previous period, and for how many prompts a current answer cites the page.", "description": "Returns the visits from AI assistants per landing page in the period (GA4), most first: per AI, engaged sessions, key events, revenue, the sessions in the previous period, and for how many prompts a current answer cites the page. Empty without GA4 data.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "type": "string", "description": "The site: its id from list_sites, or the id in the app’s address." }, "from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "First day of the period, YYYY-MM-DD; give it together with to. Without from and to, the period is the last 28 days up to yesterday, against the 28 days before." }, "to": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Last day of the period, YYYY-MM-DD (at most yesterday); give it together with from. The previous period is then the same days one month earlier." }, "limit": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 500, "description": "Pages per call." }, "cursor": { "type": "string", "description": "meta.next_cursor of the previous call, for the next page." } }, "required": [ "site_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "url": { "description": "The landing page; null for GA4's (not set).", "type": [ "string", "null" ] }, "path": { "description": "Its path with the query string, without tracking parameters (utm_*, gclid, fbclid, msclkid, srsltid); (not set) as GA4 gives it.", "type": "string" }, "sessions": { "description": "Sessions from AI assistants.", "type": "integer" }, "sessions_previous": { "description": "The same in the previous period.", "type": "integer" }, "engaged_sessions": { "description": "Engaged sessions.", "type": "integer" }, "conversions": { "description": "Key events.", "type": "number" }, "revenue_eur": { "description": "Revenue in euro.", "type": "number" }, "per_engine": { "description": "Sessions per AI, most first.", "type": "array", "items": { "type": "object", "properties": { "key": { "description": "chatgpt, perplexity, …", "type": "string" }, "label": { "description": "The name to show.", "type": "string" }, "sessions": { "description": "Sessions.", "type": "integer" } }, "required": [ "key", "label", "sessions" ] } }, "cited_by_prompts": { "description": "For how many prompts a current answer cites this page.", "type": "integer" } }, "required": [ "url", "path", "sessions", "sessions_previous", "engaged_sessions", "conversions", "revenue_eur", "per_engine", "cited_by_prompts" ] } }, "meta": { "type": "object", "description": "site_id; next_cursor and total for a list; period {from, to, compare_from, compare_to} where the endpoint covers a period." } }, "required": [ "data", "meta" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/rest/v1/aiinsights.traffic_monthly": { "post": { "operationId": "aiinsights_traffic_monthly", "tags": [ "aiinsights" ], "summary": "Returns the visits from AI assistants per month for the 16 months up to the month of to (GA4): sessions per AI, plus key events and revenue for the month.", "description": "Returns the visits from AI assistants per month for the 16 months up to the month of to (GA4): sessions per AI, plus key events and revenue for the month. The last month is incomplete until it ends (complete false). Empty without GA4 data.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "type": "string", "description": "The site: its id from list_sites, or the id in the app’s address." }, "to": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Last day, YYYY-MM-DD (at most yesterday). Defaults to yesterday." } }, "required": [ "site_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "month": { "description": "YYYY-MM.", "type": "string" }, "sessions": { "description": "Sessions from AI assistants.", "type": "integer" }, "per_engine": { "description": "Sessions per AI, most first.", "type": "array", "items": { "type": "object", "properties": { "key": { "description": "chatgpt, perplexity, …", "type": "string" }, "label": { "description": "The name to show.", "type": "string" }, "sessions": { "description": "Sessions.", "type": "integer" } }, "required": [ "key", "label", "sessions" ] } }, "conversions": { "description": "Key events.", "type": "number" }, "revenue_eur": { "description": "Revenue in euro.", "type": "number" }, "complete": { "description": "Whether the month is over (false for the month of to, unless to is its last day).", "type": "boolean" } }, "required": [ "month", "sessions", "per_engine", "conversions", "revenue_eur", "complete" ] } }, "meta": { "type": "object", "description": "site_id; next_cursor and total for a list; period {from, to, compare_from, compare_to} where the endpoint covers a period." } }, "required": [ "data", "meta" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/rest/v1/aiinsights.ai_overviews": { "post": { "operationId": "aiinsights_ai_overviews", "tags": [ "aiinsights" ], "summary": "Returns Google's AI Overview at the site's Rank tracker keywords, one item per keyword with an AI Overview reading (its latest measurement): whether Google showed an AI Overview, the site's place among its sources, the other sites it cites, and the organic position.", "description": "Returns Google's AI Overview at the site's Rank tracker keywords, one item per keyword with an AI Overview reading (its latest measurement): whether Google showed an AI Overview, the site's place among its sources, the other sites it cites, and the organic position. Keywords with an AI Overview come first, then by the site's place, then by keyword. Needs keywords in the Rank tracker.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "type": "string", "description": "The site: its id from list_sites, or the id in the app’s address." } }, "required": [ "site_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "keyword_id": { "description": "The keyword id in the Rank tracker.", "type": "string" }, "keyword": { "description": "The keyword.", "type": "string" }, "country": { "description": "Two-letter country code.", "type": "string" }, "device": { "description": "desktop or mobile.", "type": "string" }, "ai_overview": { "description": "Whether Google showed an AI Overview.", "type": "boolean" }, "position": { "description": "The site's place among the AI Overview's sources; null when not cited.", "type": [ "integer", "null" ] }, "also_cited": { "description": "Other domains among its sources, at most 3.", "type": "array", "items": { "type": "string" } }, "organic_position": { "description": "The site's best organic position in the same measurement; null when not in the measured top.", "type": [ "integer", "null" ] }, "measured_at": { "description": "When it was measured, ISO 8601 UTC.", "type": "string" } }, "required": [ "keyword_id", "keyword", "country", "device", "ai_overview", "position", "also_cited", "organic_position", "measured_at" ] } }, "meta": { "type": "object", "description": "site_id; next_cursor and total for a list; period {from, to, compare_from, compare_to} where the endpoint covers a period." } }, "required": [ "data", "meta" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } } }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "Your personal API key, shown on the MCP page in the app (/mcp)." } }, "responses": { "Error": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }