API & MCP / Reports
SEO report API to build, update and print client PDFs from your own system.
Put together client reports from 30 sections across Search Insights, the Rank tracker, AI Insights, the SEO audit, Analytics and Google Ads, with your own heading and commentary on every page. Check that every account is connected, then generate the branded PDF with a 24-hour signed download link on your own domain. Every report is also readable in Claude and ChatGPT through the MCP, and both the API and MCP are in every plan at no extra cost.
30 sections
Each page shows one view from Search Insights, the Rank tracker, AI Insights, the SEO audit, Analytics, Google Ads and four more tools.
Your own commentary
Write a custom heading and explanation above every section with bold, italics, underline, line breaks and links.
Connection check
Check per page whether the tool is switched on and the Google or Meta account is connected before you run the PDF.
Signed PDF links
Print the PDF in your white label's cover and colours, then hand out a 24-hour download link on your own domain.
Endpoints and MCP tools for client reports
A report is an ordered list of up to 100 pages for one site (excluding the cover page, which we add automatically) and a period of 1 to 24 months in YYYY-MM format. Each page combines a section key from the catalogue across Search Insights, Rank tracker, AI Insights, SEO audit, Analytics, Google Ads, Facebook Ads, Core Web Vitals, Uptime and Linkbuilding with your own heading and text, or uses section: null for a text-only page. Simple formatting stays intact in headings and texts: <b>, <strong>, <i>, <em>, <u>, <br> and <a href="https://…">. You can call all five reading endpoints in the REST API and as MCP tools (get_reports_*). Creating, updating, copying, deleting and generating a report run through the REST API.
| Endpoint | MCP tool | What it returns or does |
|---|---|---|
reports.sections |
get_reports_sections |
The 30 sections a report page can show for this site, grouped by tool, with available and unavailable_reason (tool_off or not_connected). |
reports.list |
get_reports_list |
All reports of the site, oldest first, with name, page_count (excluding the cover page), period and the state of the latest PDF. |
reports.get |
get_reports_get |
One report in full: name, period, every page in order with position, section, section_label, heading and text, and the latest PDF state. |
reports.check |
get_reports_check |
Checks per page whether it will show data in the PDF (ok, empty, tool_off, not_connected or retired), with ready and pages_ok. |
reports.status |
get_reports_status |
The state of the latest PDF (none, pending, done or failed) and a 24-hour signed download_url when done. |
reports.create |
API only | Creates a new report from a name (up to 120 characters) with optional pages and period, then returns the saved report. |
reports.update |
API only | Updates a report. Only what you send changes: name, the whole list of pages in the new order, or period. |
reports.copy |
API only | Copies a report and all its pages to the same site or another client site (to_site_id), with an empty period and no PDF. |
reports.delete |
API only | Permanently deletes a report and its PDF link; returns id and deleted: true. |
reports.generate |
API only | Starts building the PDF for the given or saved period. Returns status: "pending", or 409 on empty_report and pdf_pending. |
Fetch a report with its pages and PDF state
Every endpoint takes a POST request to /rest/v1/<endpoint> with your API key in the Authorization: Bearer header. The five reading endpoints also accept GET with query parameters. Here is reports.get for a monthly client report:
curl -X POST https://app.marketingtracer.com/rest/v1/reports.get \
-H "Authorization: Bearer mtk_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"site_id": "65a1b2c3d4e5f60718293a4b", "report_id": "6b0c1d2e3f4a5b6c7d8e9f02"}'
{
"data": {
"id": "6b0c1d2e3f4a5b6c7d8e9f02",
"name": "Monthly report",
"period": {
"from": "2026-10",
"to": "2026-10"
},
"pages": [
{
"position": 1,
"section": "searchconsole.overview",
"section_label": "Search Insights: Overview",
"heading": "Search Console in one look",
"text": "Clicks fell after the August update; the forum pages carried the month."
},
{
"position": 2,
"section": "searchconsole.topics",
"section_label": "Search Insights: Topics",
"heading": "Topics",
"text": "Baby names grow, pregnancy symptoms hold steady."
},
…
{
"position": 6,
"section": "serp.keywords",
"section_label": "Rank tracker: Keywords",
"heading": "Keywords",
"text": "Positions of the 100 keywords we track."
},
…
],
"pdf": {
"status": "done",
"period": {
"from": "2026-10",
"to": "2026-10"
},
"requested_at": "2026-11-01T11:00:00Z",
"completed_at": "2026-11-01T11:01:45Z"
},
"created_at": "2026-10-27T11:00:00Z",
"updated_at": "2026-11-01T10:59:50Z"
},
"meta": {
"site_id": "65a1b2c3d4e5f60718293a4b"
}
}
Copy your standard report to a new client and check every connection on day one
When a new client signs on, your onboarding script calls reports.copy with to_site_id to put your agency's standard report on the new site.
Right after, it runs reports.check on the copy to get ok, tool_off or not_connected for every page. Your account manager sees straight away if Google Analytics or Search Console still needs to be linked while the client is on the phone.
// POST /rest/v1/reports.copy
{
"site_id": "65a1b2c3d4e5f60718293a4b",
"report_id": "6b0c1d2e3f4a5b6c7d8e9f02",
"to_site_id": "65a1b2c3d4e5f60718293a4c"
}
// POST /rest/v1/reports.check
{
"data": {
"report_id": "6b0c1d2e3f4a5b6c7d8e9f02",
"ready": true,
"pages_ok": 7,
"pages": [
{
"position": 1,
"section": "searchconsole.overview",
"status": "ok"
},
{
"position": 2,
"section": "searchconsole.topics",
"status": "ok"
},
…
]
},
"meta": {
"site_id": "65a1b2c3d4e5f60718293a4b"
}
}
// POST /rest/v1/reports.update
{
"site_id": "65a1b2c3d4e5f60718293a4b",
"report_id": "6b0c1d2e3f4a5b6c7d8e9f02",
"pages": [
{
"section": "searchconsole.overview",
"heading": "Search Console in one look",
"text": "Clicks fell after the August update; the forum pages carried the month."
},
{
"section": "searchconsole.topics",
"heading": "Topics",
"text": "Baby names grow, pregnancy symptoms hold steady."
}
]
}
Draft the explanation above each chart from the month's real numbers
The charts in a monthly report fill themselves, but clients read it for your explanation above each section. Writing a clear takeaway per page across dozens of client sites takes Monday morning.
In Claude or ChatGPT, get_reports_get reads the report's pages and sections. Next to it, the Search Console, Rank tracker and Analytics MCP tools pull what changed that month. Your AI drafts the heading and paragraph for each page from those numbers, and your script saves the updated pages list with reports.update.
Print the monthly PDFs in your own brand and send a direct download link
On the first of the month, your system calls reports.generate with last month's period ({"from": "2026-10"}). MarketingTracer builds the PDF with your white label's cover, header, footer, logo and colours.
Your script checks reports.status until status is done and reads download_url. That signed link on your white-label domain works for 24 hours with no login, so you can drop it straight into your client portal or monthly email.
// POST /rest/v1/reports.generate
{
"site_id": "65a1b2c3d4e5f60718293a4b",
"report_id": "6b0c1d2e3f4a5b6c7d8e9f02",
"period": {"from": "2026-10"}
}
// POST /rest/v1/reports.status
{
"data": {
"status": "done",
"period": {"from": "2026-10", "to": "2026-10"},
"requested_at": "2026-11-01T11:00:00Z",
"completed_at": "2026-11-01T11:01:45Z",
"report_id": "6b0c1d2e3f4a5b6c7d8e9f02",
"download_url": "https://app.marketingtracer.com/rest/web/reports.download?site=65a1b2c3d4e5f60718293a4b&report=6b0c1d2e3f4a5b6c7d8e9f02&exp=1794086400&sig=3f1c…",
"download_expires_at": "2026-11-13T00:00:00Z"
},
"meta": {
"site_id": "65a1b2c3d4e5f60718293a4b"
}
}
Endpoints, arguments and field descriptions
Every endpoint is a POST with a JSON body; reading endpoints also take a GET with the same arguments in the query string. Send your API key as Authorization: Bearer YOUR_API_KEY. Every answer is {"data": …, "meta": {…}}: meta.site_id always, meta.next_cursor and meta.total for a list, meta.period where the endpoint covers a period. An error is {"error": {"code", "message"}} with the HTTP status: 400 invalid_argument, unknown_argument or missing_argument; 401 not_authenticated; 403 no_access or tool_off; 404 not_found; 409 not_connected (a connection the endpoint needs, such as Google Analytics 4, is missing); 429 rate_limited; 502 google_error (Google returned an error on your own Search Console or Analytics connection) or upstream_error (another data source did not answer; try again in a minute). The machine-readable version is openapi.json.
reports.sections
POST /rest/v1/reports.sections · MCP tool get_reports_sections
Returns the sections a report page can show for this site, grouped per tool: a fixed list of keys you use in reports.create and reports.update. Per section whether it is available here: a section is unavailable when its tool is off for this site or its data source is not connected (connecting is done by a person in the app, on the tool's page).
Arguments
| Argument | Type | What it does |
|---|---|---|
site_id (required) | string | The site: its id from list_sites, or the id in the app’s address. |
Example request
curl -X POST https://app.marketingtracer.com/rest/v1/reports.sections \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"site_id":"YOUR_SITE_ID"}'
Example response · Search Console and Google Analytics are connected on this site; Google Ads and Meta Ads are not.
{
"data": [
{
"key": "searchconsole.overview",
"group": "searchconsole",
"group_label": "Search Insights",
"label": "Overview",
"needs_connection": true,
"available": true,
"unavailable_reason": null
},
{
"key": "searchconsole.topics",
"group": "searchconsole",
"group_label": "Search Insights",
"label": "Topics",
"needs_connection": true,
"available": true,
"unavailable_reason": null
},
{
"key": "searchconsole.tracked",
"group": "searchconsole",
"group_label": "Search Insights",
"label": "Tracked keywords",
"needs_connection": true,
"available": true,
"unavailable_reason": null
},
{
"key": "searchconsole.actions",
"group": "searchconsole",
"group_label": "Search Insights",
"label": "Opportunities",
"needs_connection": true,
"available": true,
"unavailable_reason": null
},
{
"key": "searchconsole.queries",
"group": "searchconsole",
"group_label": "Search Insights",
"label": "Search queries",
"needs_connection": true,
"available": true,
"unavailable_reason": null
},
{
"key": "searchconsole.pages",
"group": "searchconsole",
"group_label": "Search Insights",
"label": "Pages",
"needs_connection": true,
"available": true,
"unavailable_reason": null
},
{
"key": "serp.overview",
"group": "serp",
"group_label": "Rank tracker",
"label": "Insights",
"needs_connection": false,
"available": true,
"unavailable_reason": null
},
{
"key": "serp.keywords",
"group": "serp",
"group_label": "Rank tracker",
"label": "Keywords",
"needs_connection": false,
"available": true,
"unavailable_reason": null
},
{
"key": "serp.competitors",
"group": "serp",
"group_label": "Rank tracker",
"label": "Competitors",
"needs_connection": false,
"available": true,
"unavailable_reason": null
},
{
"key": "aiinsights.overview",
"group": "aiinsights",
"group_label": "AI Insights",
"label": "Overview",
"needs_connection": false,
"available": true,
"unavailable_reason": null
},
{
"key": "aiinsights.competitors",
"group": "aiinsights",
"group_label": "AI Insights",
"label": "Competitors",
"needs_connection": false,
"available": true,
"unavailable_reason": null
},
{
"key": "aiinsights.traffic",
"group": "aiinsights",
"group_label": "AI Insights",
"label": "AI traffic",
"needs_connection": false,
"available": true,
"unavailable_reason": null
},
{
"key": "scan.overview",
"group": "scan",
"group_label": "SEO audit",
"label": "Overview",
"needs_connection": false,
"available": true,
"unavailable_reason": null
},
{
"key": "analytics.channels",
"group": "analytics",
"group_label": "Analytics",
"label": "All channels",
"needs_connection": true,
"available": true,
"unavailable_reason": null
},
{
"key": "analytics.organic",
"group": "analytics",
"group_label": "Analytics",
"label": "Organic search",
"needs_connection": true,
"available": true,
"unavailable_reason": null
},
{
"key": "analytics.paid",
"group": "analytics",
"group_label": "Analytics",
"label": "Paid search",
"needs_connection": true,
"available": true,
"unavailable_reason": null
},
{
"key": "analytics.social",
"group": "analytics",
"group_label": "Analytics",
"label": "Social",
"needs_connection": true,
"available": true,
"unavailable_reason": null
},
{
"key": "analytics.referral",
"group": "analytics",
"group_label": "Analytics",
"label": "Referral",
"needs_connection": true,
"available": true,
"unavailable_reason": null
},
{
"key": "googleads.campaigns",
"group": "googleads",
"group_label": "Google Ads",
"label": "Campaigns",
"needs_connection": true,
"available": false,
"unavailable_reason": "not_connected"
},
{
"key": "googleads.adgroups",
"group": "googleads",
"group_label": "Google Ads",
"label": "Ad groups",
"needs_connection": true,
"available": false,
"unavailable_reason": "not_connected"
},
{
"key": "googleads.keywords",
"group": "googleads",
"group_label": "Google Ads",
"label": "Keywords",
"needs_connection": true,
"available": false,
"unavailable_reason": "not_connected"
},
{
"key": "facebookads.campaigns",
"group": "facebookads",
"group_label": "Facebook Ads",
"label": "Campaigns",
"needs_connection": true,
"available": false,
"unavailable_reason": "not_connected"
},
{
"key": "facebookads.adsets",
"group": "facebookads",
"group_label": "Facebook Ads",
"label": "Ad sets",
"needs_connection": true,
"available": false,
"unavailable_reason": "not_connected"
},
{
"key": "facebookads.ads",
"group": "facebookads",
"group_label": "Facebook Ads",
"label": "Ads",
"needs_connection": true,
"available": false,
"unavailable_reason": "not_connected"
},
{
"key": "facebookads.age",
"group": "facebookads",
"group_label": "Facebook Ads",
"label": "Age",
"needs_connection": true,
"available": false,
"unavailable_reason": "not_connected"
},
{
"key": "facebookads.gender",
"group": "facebookads",
"group_label": "Facebook Ads",
"label": "Gender",
"needs_connection": true,
"available": false,
"unavailable_reason": "not_connected"
},
{
"key": "crux.overview",
"group": "crux",
"group_label": "Core Web Vitals",
"label": "Overview",
"needs_connection": false,
"available": true,
"unavailable_reason": null
},
{
"key": "crux.diagnose",
"group": "crux",
"group_label": "Core Web Vitals",
"label": "Diagnosis",
"needs_connection": false,
"available": true,
"unavailable_reason": null
},
{
"key": "uptime.month",
"group": "uptime",
"group_label": "Uptime",
"label": "Availability and incidents",
"needs_connection": false,
"available": true,
"unavailable_reason": null
},
{
"key": "linkbuilding.overview",
"group": "linkbuilding",
"group_label": "Linkbuilding",
"label": "Overview",
"needs_connection": false,
"available": true,
"unavailable_reason": null
}
],
"meta": {"site_id": "YOUR_SITE_ID", "next_cursor": null, "total": 30}
}
Response fields · data is a list; each item has:
| Field | Type | What it is |
|---|---|---|
key | string | The section key, e.g. serp.keywords. |
group | string | The tool, e.g. serp. |
group_label | string | The tool in words, e.g. Rank tracker. |
label | string | The section in words, e.g. Keywords. |
needs_connection | boolean | Whether the tool needs a connected account (Search Console, Google Analytics, Google Ads, Meta Ads). |
available | boolean | Whether a page with this section shows data for this site now. |
unavailable_reason | string or null | tool_off (the tool is off for this site) or not_connected (connect it in the app first); null when available. |
reports.list
POST /rest/v1/reports.list · MCP tool get_reports_list
Returns the reports of the site, oldest first: name, number of pages, the months it covers and the state of its latest PDF.
Arguments
| Argument | Type | What it does |
|---|---|---|
site_id (required) | string | The site: its id from list_sites, or the id in the app’s address. |
Example request
curl -X POST https://app.marketingtracer.com/rest/v1/reports.list \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"site_id":"YOUR_SITE_ID"}'
Example response · The first report is from before 13 November 2026, so it has no created_at.
{
"data": [
{
"id": "6b0c1d2e3f4a5b6c7d8e9f01",
"name": "Short report",
"page_count": 2,
"period": {"from": "2026-09", "to": "2026-09"},
"pdf": {
"status": "done",
"period": {"from": "2026-09", "to": "2026-09"},
"requested_at": null,
"completed_at": null
},
"created_at": null,
"updated_at": null
},
{
"id": "6b0c1d2e3f4a5b6c7d8e9f02",
"name": "Monthly report",
"page_count": 7,
"period": {"from": "2026-10", "to": "2026-10"},
"pdf": {
"status": "done",
"period": {"from": "2026-10", "to": "2026-10"},
"requested_at": "2026-11-01T11:00:00Z",
"completed_at": "2026-11-01T11:01:45Z"
},
"created_at": "2026-10-27T11:00:00Z",
"updated_at": "2026-11-01T10:59:50Z"
}
],
"meta": {"site_id": "YOUR_SITE_ID", "next_cursor": null, "total": 2}
}
Response fields · data is a list; each item has:
| Field | Type | What it is |
|---|---|---|
id | string | The report id. |
name | string | The name of the report. |
page_count | integer | Number of pages, without the cover page. |
period | object or null | The months the report covers, YYYY-MM, to included; null when no period is set yet. |
period.from | string | First month, YYYY-MM. |
period.to | string | Last month, YYYY-MM (the same as from for one month). |
pdf | object | The latest PDF of the report. |
pdf.status | string | none (never made), pending (being made, usually one to three minutes), done or failed. |
pdf.period | object or null | The months of that PDF, {from, to}; null when none was made. |
pdf.period.from | string | YYYY-MM. |
pdf.period.to | string | YYYY-MM. |
pdf.requested_at | string or null | When it was started, ISO 8601 UTC; null when not known. |
pdf.completed_at | string or null | When it was done or failed, ISO 8601 UTC; null while pending or not known. |
created_at | string or null | When the report was made, ISO 8601 UTC; null for reports from before 13 November 2026. |
updated_at | string or null | When it was last changed, ISO 8601 UTC; null when not known. |
reports.get
POST /rest/v1/reports.get · MCP tool get_reports_get
Returns one report: its name, the months it covers, every page with its section, heading and text, and the state of its latest PDF.
Arguments
| Argument | Type | What it does |
|---|---|---|
site_id (required) | string | The site: its id from list_sites, or the id in the app’s address. |
report_id (required) | string | The report: its id from reports.list. |
Example request
curl -X POST https://app.marketingtracer.com/rest/v1/reports.get \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"site_id":"YOUR_SITE_ID","report_id":"6b0c1d2e3f4a5b6c7d8e9f02"}'
Example response · Headings and text are illustrative.
{
"data": {
"id": "6b0c1d2e3f4a5b6c7d8e9f02",
"name": "Monthly report",
"period": {"from": "2026-10", "to": "2026-10"},
"pages": [
{
"position": 1,
"section": "searchconsole.overview",
"section_label": "Search Insights: Overview",
"heading": "Search Console in one look",
"text": "Clicks fell after the August update; the forum pages carried the month."
},
{
"position": 2,
"section": "searchconsole.topics",
"section_label": "Search Insights: Topics",
"heading": "Topics",
"text": "Baby names grow, pregnancy symptoms hold steady."
},
{
"position": 3,
"section": "searchconsole.tracked",
"section_label": "Search Insights: Tracked keywords",
"heading": "Tracked keywords",
"text": ""
},
{
"position": 4,
"section": "searchconsole.actions",
"section_label": "Search Insights: Opportunities",
"heading": "What to do next",
"text": "The three opportunities we pick up this month."
},
{
"position": 5,
"section": "serp.overview",
"section_label": "Rank tracker: Insights",
"heading": "Rank tracker",
"text": ""
},
{
"position": 6,
"section": "serp.keywords",
"section_label": "Rank tracker: Keywords",
"heading": "Keywords",
"text": "Positions of the 100 keywords we track."
},
{
"position": 7,
"section": "serp.competitors",
"section_label": "Rank tracker: Competitors",
"heading": "Competitors",
"text": ""
}
],
"pdf": {
"status": "done",
"period": {"from": "2026-10", "to": "2026-10"},
"requested_at": "2026-11-01T11:00:00Z",
"completed_at": "2026-11-01T11:01:45Z"
},
"created_at": "2026-10-27T11:00:00Z",
"updated_at": "2026-11-01T10:59:50Z"
},
"meta": {"site_id": "YOUR_SITE_ID"}
}
Response fields · in data:
| Field | Type | What it is |
|---|---|---|
id | string | The report id. |
name | string | The name of the report. |
period | object or null | The months the report covers, YYYY-MM, to included; null when no period is set yet. |
period.from | string | First month, YYYY-MM. |
period.to | string | Last month, YYYY-MM (the same as from for one month). |
pages | array | The pages in order, without the cover page. |
pages[].position | integer | Page number in the report, 1 for the first page after the cover. |
pages[].section | string or null | The section key (see reports.sections); retired for a section of a tool that no longer exists (the heading and text stay, the data not); null for a page without data. |
pages[].section_label | string or null | The section in words, e.g. "Rank tracker: Keywords"; null without a section. |
pages[].heading | string | The heading of the page. |
pages[].text | string | The text under the heading. |
pdf | object | The latest PDF of the report. |
pdf.status | string | none (never made), pending (being made, usually one to three minutes), done or failed. |
pdf.period | object or null | The months of that PDF, {from, to}; null when none was made. |
pdf.period.from | string | YYYY-MM. |
pdf.period.to | string | YYYY-MM. |
pdf.requested_at | string or null | When it was started, ISO 8601 UTC; null when not known. |
pdf.completed_at | string or null | When it was done or failed, ISO 8601 UTC; null while pending or not known. |
created_at | string or null | When the report was made, ISO 8601 UTC; null for reports from before 13 November 2026. |
updated_at | string or null | When it was last changed, ISO 8601 UTC; null when not known. |
reports.check
POST /rest/v1/reports.check · MCP tool get_reports_check
Returns per page whether it will show data in the PDF: ok, empty (no section chosen), tool_off (the tool is off for this site), not_connected (connect the data source in the app first) or retired (the tool no longer exists; choose another section). ready is true when every page is ok. Use it before reports.generate.
Arguments
| Argument | Type | What it does |
|---|---|---|
site_id (required) | string | The site: its id from list_sites, or the id in the app’s address. |
report_id (required) | string | The report: its id from reports.list. |
Example request
curl -X POST https://app.marketingtracer.com/rest/v1/reports.check \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"site_id":"YOUR_SITE_ID","report_id":"6b0c1d2e3f4a5b6c7d8e9f02"}'
Example response ·
{
"data": {
"report_id": "6b0c1d2e3f4a5b6c7d8e9f02",
"ready": true,
"pages_ok": 7,
"pages": [
{"position": 1, "section": "searchconsole.overview", "status": "ok"},
{"position": 2, "section": "searchconsole.topics", "status": "ok"},
{"position": 3, "section": "searchconsole.tracked", "status": "ok"},
{"position": 4, "section": "searchconsole.actions", "status": "ok"},
{"position": 5, "section": "serp.overview", "status": "ok"},
{"position": 6, "section": "serp.keywords", "status": "ok"},
{"position": 7, "section": "serp.competitors", "status": "ok"}
]
},
"meta": {"site_id": "YOUR_SITE_ID"}
}
Response fields · in data:
| Field | Type | What it is |
|---|---|---|
report_id | string | The report id. |
ready | boolean | Whether the report has pages and every page is ok. |
pages_ok | integer | Number of pages that are ok. |
pages | array | Per page, in order. |
pages[].position | integer | Page number, 1 for the first page after the cover. |
pages[].section | string or null | The section key; null without a section. |
pages[].status | string | ok, empty, tool_off, not_connected or retired. |
reports.status
POST /rest/v1/reports.status · MCP tool get_reports_status
Returns the state of the latest PDF of a report and, when it is done, a download link that works for 24 hours without logging in. A PDF usually takes one to three minutes; check again every 20 seconds or so while it is pending.
Arguments
| Argument | Type | What it does |
|---|---|---|
site_id (required) | string | The site: its id from list_sites, or the id in the app’s address. |
report_id (required) | string | The report: its id from reports.list. |
Example request
curl -X POST https://app.marketingtracer.com/rest/v1/reports.status \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"site_id":"YOUR_SITE_ID","report_id":"6b0c1d2e3f4a5b6c7d8e9f02"}'
Example response · The signature in the link is shortened here.
{
"data": {
"status": "done",
"period": {"from": "2026-10", "to": "2026-10"},
"requested_at": "2026-11-01T11:00:00Z",
"completed_at": "2026-11-01T11:01:45Z",
"report_id": "6b0c1d2e3f4a5b6c7d8e9f02",
"download_url": "https://app.marketingtracer.com/rest/web/reports.download?site=65a1b2c3d4e5f60718293a4b&report=6b0c1d2e3f4a5b6c7d8e9f02&exp=1794086400&sig=3f1c…",
"download_expires_at": "2026-11-13T00:00:00Z"
},
"meta": {"site_id": "YOUR_SITE_ID"}
}
Response fields · in data:
| Field | Type | What it is |
|---|---|---|
report_id | string | The report id. |
status | string | none (never made), pending (being made), done or failed (start it again with reports.generate). |
period | object or null | The months of the PDF, {from, to}; null when none was made. |
period.from | string | YYYY-MM. |
period.to | string | YYYY-MM. |
requested_at | string or null | When it was started, ISO 8601 UTC; null when not known. |
completed_at | string or null | When it was done or failed, ISO 8601 UTC; null while pending or not known. |
download_url | string or null | The PDF, as a signed link that works without logging in; null unless status is done. |
download_expires_at | string or null | Until when the link works, ISO 8601 UTC; null without a link. |
reports.create
POST /rest/v1/reports.create · MCP tool
Returns the new report after making it. Give it a name and, if you like, its pages and period now; you can change them later with reports.update.
Arguments
| Argument | Type | What it does |
|---|---|---|
site_id (required) | string | The site: its id from list_sites, or the id in the app’s address. |
name (required) | string | The name of the report, at most 120 characters. |
pages | list of object | The pages of the report in order (the cover page is added by itself), at most 100. Each page: {section, heading, text}: section a key from reports.sections (or null for a page without data), heading and text your own words about that page. Simple formatting is kept (<b>, <strong>, <i>, <em>, <u>, <br>, and links <a href="https://…">); any other < is shown as text. |
period | object | The months the report covers: {from, to} as YYYY-MM, to included; to may be left out for one month. At most 24 months, ending this month at the latest. |
Example request
curl -X POST https://app.marketingtracer.com/rest/v1/reports.create \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"site_id":"YOUR_SITE_ID","name":"Monthly report","pages":[{"section":"searchconsole.overview","heading":"Search Console in one look","text":"Clicks fell after the August update; the forum pages carried the month."},{"section":"searchconsole.topics","heading":"Topics","text":"Baby names grow, pregnancy symptoms hold steady."}],"period":{"from":"2026-10"}}'
Example response ·
{
"data": {
"id": "6b0c1d2e3f4a5b6c7d8e9f03",
"name": "Monthly report",
"period": {"from": "2026-10", "to": "2026-10"},
"pages": [
{
"position": 1,
"section": "searchconsole.overview",
"section_label": "Search Insights: Overview",
"heading": "Search Console in one look",
"text": "Clicks fell after the August update; the forum pages carried the month."
},
{
"position": 2,
"section": "searchconsole.topics",
"section_label": "Search Insights: Topics",
"heading": "Topics",
"text": "Baby names grow, pregnancy symptoms hold steady."
}
],
"pdf": {"status": "none", "period": null, "requested_at": null, "completed_at": null},
"created_at": "2026-11-06T22:20:00Z",
"updated_at": "2026-11-06T22:20:00Z"
},
"meta": {"site_id": "YOUR_SITE_ID"}
}
Response fields · in data:
| Field | Type | What it is |
|---|---|---|
id | string | The report id. |
name | string | The name. |
period | object or null | The months the report covers, YYYY-MM, to included; null when no period is set yet. |
period.from | string | First month, YYYY-MM. |
period.to | string | Last month, YYYY-MM (the same as from for one month). |
pages | array | The pages in order, without the cover page. |
pages[].position | integer | Page number in the report, 1 for the first page after the cover. |
pages[].section | string or null | The section key (see reports.sections); retired for a section of a tool that no longer exists (the heading and text stay, the data not); null for a page without data. |
pages[].section_label | string or null | The section in words, e.g. "Rank tracker: Keywords"; null without a section. |
pages[].heading | string | The heading of the page. |
pages[].text | string | The text under the heading. |
pdf | object | The latest PDF of the report. |
pdf.status | string | none (never made), pending (being made, usually one to three minutes), done or failed. |
pdf.period | object or null | The months of that PDF, {from, to}; null when none was made. |
pdf.period.from | string | YYYY-MM. |
pdf.period.to | string | YYYY-MM. |
pdf.requested_at | string or null | When it was started, ISO 8601 UTC; null when not known. |
pdf.completed_at | string or null | When it was done or failed, ISO 8601 UTC; null while pending or not known. |
created_at | string or null | When the report was made, ISO 8601 UTC. |
updated_at | string or null | When it was last changed, ISO 8601 UTC. |
reports.update
POST /rest/v1/reports.update · MCP tool
Returns the report after changing it. Only what you send changes: name, the whole list of pages (send them all, in the new order; an empty list removes every page), or the period.
Arguments
| Argument | Type | What it does |
|---|---|---|
site_id (required) | string | The site: its id from list_sites, or the id in the app’s address. |
report_id (required) | string | The report: its id from reports.list. |
name | string | The new name, at most 120 characters. |
pages | list of object | The pages of the report in order (the cover page is added by itself), at most 100. Each page: {section, heading, text}: section a key from reports.sections (or null for a page without data), heading and text your own words about that page. Simple formatting is kept (<b>, <strong>, <i>, <em>, <u>, <br>, and links <a href="https://…">); any other < is shown as text. |
period | object | The months the report covers: {from, to} as YYYY-MM, to included; to may be left out for one month. At most 24 months, ending this month at the latest. |
Example request
curl -X POST https://app.marketingtracer.com/rest/v1/reports.update \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"site_id":"YOUR_SITE_ID","report_id":"6b0c1d2e3f4a5b6c7d8e9f02","pages":[{"section":"searchconsole.overview","heading":"Search Console in one look","text":"Clicks fell after the August update; the forum pages carried the month."},{"section":"searchconsole.topics","heading":"Topics","text":"Baby names grow, pregnancy symptoms hold steady."}]}'
Example response · Only the pages were sent, so the name and period stay.
{
"data": {
"id": "6b0c1d2e3f4a5b6c7d8e9f02",
"name": "Monthly report",
"period": {"from": "2026-10", "to": "2026-10"},
"pages": [
{
"position": 1,
"section": "searchconsole.overview",
"section_label": "Search Insights: Overview",
"heading": "Search Console in one look",
"text": "Clicks fell after the August update; the forum pages carried the month."
},
{
"position": 2,
"section": "searchconsole.topics",
"section_label": "Search Insights: Topics",
"heading": "Topics",
"text": "Baby names grow, pregnancy symptoms hold steady."
}
],
"pdf": {
"status": "done",
"period": {"from": "2026-10", "to": "2026-10"},
"requested_at": "2026-11-01T11:00:00Z",
"completed_at": "2026-11-01T11:01:45Z"
},
"created_at": "2026-10-27T11:00:00Z",
"updated_at": "2026-11-06T22:30:00Z"
},
"meta": {"site_id": "YOUR_SITE_ID"}
}
Response fields · in data:
| Field | Type | What it is |
|---|---|---|
id | string | The report id. |
name | string | The name. |
period | object or null | The months the report covers, YYYY-MM, to included; null when no period is set yet. |
period.from | string | First month, YYYY-MM. |
period.to | string | Last month, YYYY-MM (the same as from for one month). |
pages | array | The pages in order, without the cover page. |
pages[].position | integer | Page number in the report, 1 for the first page after the cover. |
pages[].section | string or null | The section key (see reports.sections); retired for a section of a tool that no longer exists (the heading and text stay, the data not); null for a page without data. |
pages[].section_label | string or null | The section in words, e.g. "Rank tracker: Keywords"; null without a section. |
pages[].heading | string | The heading of the page. |
pages[].text | string | The text under the heading. |
pdf | object | The latest PDF of the report. |
pdf.status | string | none (never made), pending (being made, usually one to three minutes), done or failed. |
pdf.period | object or null | The months of that PDF, {from, to}; null when none was made. |
pdf.period.from | string | YYYY-MM. |
pdf.period.to | string | YYYY-MM. |
pdf.requested_at | string or null | When it was started, ISO 8601 UTC; null when not known. |
pdf.completed_at | string or null | When it was done or failed, ISO 8601 UTC; null while pending or not known. |
created_at | string or null | When the report was made, ISO 8601 UTC; null for reports from before 13 November 2026. |
updated_at | string or null | When it was last changed, ISO 8601 UTC. |
reports.copy
POST /rest/v1/reports.copy · MCP tool
Returns the copy after copying the pages of a report (not its period or PDF) to a new report, on the same site or on another site of yours: the way to give a new client the same report. Run reports.check on the copy: a section may need a connection there.
Arguments
| Argument | Type | What it does |
|---|---|---|
site_id (required) | string | The site: its id from list_sites, or the id in the app’s address. |
report_id (required) | string | The report: its id from reports.list. |
to_site_id | string | The site to copy to (its id from list_sites); leave out for the same site. You need to be able to edit reports there. |
name | string | The name of the copy; default the same name, with "(copy)" on the same site. |
Example request
curl -X POST https://app.marketingtracer.com/rest/v1/reports.copy \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"site_id":"YOUR_SITE_ID","report_id":"6b0c1d2e3f4a5b6c7d8e9f02","to_site_id":"65a1b2c3d4e5f60718293a4c"}'
Example response ·
{
"data": {
"id": "6b0c1d2e3f4a5b6c7d8e9f04",
"name": "Monthly report",
"period": null,
"pages": [
{
"position": 1,
"section": "searchconsole.overview",
"section_label": "Search Insights: Overview",
"heading": "Search Console in one look",
"text": "Clicks fell after the August update; the forum pages carried the month."
},
{
"position": 2,
"section": "searchconsole.topics",
"section_label": "Search Insights: Topics",
"heading": "Topics",
"text": "Baby names grow, pregnancy symptoms hold steady."
},
{
"position": 3,
"section": "searchconsole.tracked",
"section_label": "Search Insights: Tracked keywords",
"heading": "Tracked keywords",
"text": ""
},
{
"position": 4,
"section": "searchconsole.actions",
"section_label": "Search Insights: Opportunities",
"heading": "What to do next",
"text": "The three opportunities we pick up this month."
},
{
"position": 5,
"section": "serp.overview",
"section_label": "Rank tracker: Insights",
"heading": "Rank tracker",
"text": ""
},
{
"position": 6,
"section": "serp.keywords",
"section_label": "Rank tracker: Keywords",
"heading": "Keywords",
"text": "Positions of the 100 keywords we track."
},
{
"position": 7,
"section": "serp.competitors",
"section_label": "Rank tracker: Competitors",
"heading": "Competitors",
"text": ""
}
],
"pdf": {"status": "none", "period": null, "requested_at": null, "completed_at": null},
"created_at": "2026-11-06T22:40:00Z",
"updated_at": "2026-11-06T22:40:00Z",
"site_id": "65a1b2c3d4e5f60718293a4c"
},
"meta": {"site_id": "YOUR_SITE_ID"}
}
Response fields · in data:
| Field | Type | What it is |
|---|---|---|
id | string | The id of the copy. |
site_id | string | The site the copy is on. |
name | string | The name of the copy. |
period | object or null | The months the report covers, YYYY-MM, to included; null when no period is set yet. |
period.from | string | First month, YYYY-MM. |
period.to | string | Last month, YYYY-MM (the same as from for one month). |
pages | array | The pages in order, without the cover page. |
pages[].position | integer | Page number in the report, 1 for the first page after the cover. |
pages[].section | string or null | The section key (see reports.sections); retired for a section of a tool that no longer exists (the heading and text stay, the data not); null for a page without data. |
pages[].section_label | string or null | The section in words, e.g. "Rank tracker: Keywords"; null without a section. |
pages[].heading | string | The heading of the page. |
pages[].text | string | The text under the heading. |
pdf | object | The latest PDF of the report. |
pdf.status | string | none (never made), pending (being made, usually one to three minutes), done or failed. |
pdf.period | object or null | The months of that PDF, {from, to}; null when none was made. |
pdf.period.from | string | YYYY-MM. |
pdf.period.to | string | YYYY-MM. |
pdf.requested_at | string or null | When it was started, ISO 8601 UTC; null when not known. |
pdf.completed_at | string or null | When it was done or failed, ISO 8601 UTC; null while pending or not known. |
created_at | string or null | When the copy was made, ISO 8601 UTC. |
updated_at | string or null | The same as created_at. |
reports.delete
POST /rest/v1/reports.delete · MCP tool
Returns the id and deleted true after deleting a report and its PDF link. This cannot be undone.
Arguments
| Argument | Type | What it does |
|---|---|---|
site_id (required) | string | The site: its id from list_sites, or the id in the app’s address. |
report_id (required) | string | The report: its id from reports.list. |
Example request
curl -X POST https://app.marketingtracer.com/rest/v1/reports.delete \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"site_id":"YOUR_SITE_ID","report_id":"6b0c1d2e3f4a5b6c7d8e9f01"}'
Example response · The answer is always this shape.
{
"data": {"id": "6b0c1d2e3f4a5b6c7d8e9f01", "deleted": true},
"meta": {"site_id": "YOUR_SITE_ID"}
}
Response fields · in data:
| Field | Type | What it is |
|---|---|---|
id | string | The id of the deleted report. |
deleted | boolean | Always true. |
reports.generate
POST /rest/v1/reports.generate · MCP tool
Returns the state of the PDF (pending) after starting it, for the period you send or the period of the report; the period you send becomes the period of the report. A PDF usually takes one to three minutes: check reports.status for the download link. Errors: 409 empty_report (no pages), 409 pdf_pending (one is being made), 502 pdf_server_error.
Arguments
| Argument | Type | What it does |
|---|---|---|
site_id (required) | string | The site: its id from list_sites, or the id in the app’s address. |
report_id (required) | string | The report: its id from reports.list. |
period | object | The months the report covers: {from, to} as YYYY-MM, to included; to may be left out for one month. At most 24 months, ending this month at the latest. |
Example request
curl -X POST https://app.marketingtracer.com/rest/v1/reports.generate \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"site_id":"YOUR_SITE_ID","report_id":"6b0c1d2e3f4a5b6c7d8e9f02","period":{"from":"2026-10"}}'
Example response ·
{
"data": {
"status": "pending",
"period": {"from": "2026-10", "to": "2026-10"},
"requested_at": "2026-11-06T22:50:00Z",
"completed_at": null,
"report_id": "6b0c1d2e3f4a5b6c7d8e9f02",
"download_url": null,
"download_expires_at": null
},
"meta": {"site_id": "YOUR_SITE_ID"}
}
Response fields · in data:
| Field | Type | What it is |
|---|---|---|
report_id | string | The report id. |
status | string | pending. |
period | object or null | The months of the PDF, {from, to}. |
period.from | string | YYYY-MM. |
period.to | string | YYYY-MM. |
requested_at | string or null | When it was started, ISO 8601 UTC. |
completed_at | string or null | null while pending. |
download_url | string or null | null while pending; see reports.status. |
download_expires_at | string or null | null while pending. |
Serve branded PDFs on your own domain with one key for every client site.
Connect your own dashboard domain and both the REST API and the MCP server answer on that host under your agency's name. One white-label key (mtw_…, 600 calls per minute) works across every client site in your account. Every PDF carries your agency's cover, header, footer and brand colours, and reports.status returns a 24-hour signed download_url on that same domain.
Free 14-day trial
MarketingTracer smart A.I. tool shows you what you need to rank. Then we'll help you get it done.
- No credit card required
- No installation needed
- No strings attached
Frequently asked questions about the SEO report API
Something else? Ask us.
Can I create or generate reports through the MCP?
No. The MCP server is read-only across all tools, so it provides the five reading tools (get_reports_sections, get_reports_list, get_reports_get, get_reports_check and get_reports_status). Creating, updating, copying, deleting and generating a PDF go through the REST API with a personal or white-label API key.
How long does generating a PDF take, and how does the download link work?
Building a PDF usually takes one to three minutes. After calling reports.generate, check reports.status every 20 seconds until status is done. The response includes download_url, a signed link on the domain you called from that works for 24 hours with no login.
What HTML formatting can I use in page headings and texts?
Headings (up to 500 characters) and page texts (up to 10,000 characters) keep <b>, <strong>, <i>, <em>, <u>, <br> and <a href="https://…"> links. Any other tag or < character is escaped and shown as plain text. Set section to null when you want a page with only your own heading and text.
How do I roll out one report template across all my client sites?
Build the report once on a template site and call reports.copy with to_site_id set to the client's site ID. That copies every page, section, heading and text to the other site and leaves the period and PDF empty. Run reports.check on the new copy to see if any section needs a connected account on that site.
What happens if a section's data source is not connected on a client site?
reports.check and reports.sections return not_connected when a section needs Search Console, Google Analytics, Google Ads or Facebook Ads and that account is not linked yet. When the module itself is switched off for the site, both endpoints return tool_off. A team member or the client links an external account once in the app.
How many pages and months can a report have?
A report can hold up to 100 pages (plus the automatic cover page) and cover 1 to 24 months in YYYY-MM format up to the current month. For a single month, send only period.from.
Is the SEO report API included in my plan?
Yes. Both the REST API and the MCP server are included in every plan at no extra cost. A personal key (mtk_…) allows 60 calls per minute across the sites in your login, and a white-label key (mtw_…) allows 600 calls per minute across every site of your white label on your own domain.