NEWAI content checker: see which pages read like AI text

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"
  }
}
Onboarding

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."
    }
  ]
}
Commentary

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.

Delivery

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

ArgumentTypeWhat it does
site_id (required)stringThe 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:

FieldTypeWhat it is
keystringThe section key, e.g. serp.keywords.
groupstringThe tool, e.g. serp.
group_labelstringThe tool in words, e.g. Rank tracker.
labelstringThe section in words, e.g. Keywords.
needs_connectionbooleanWhether the tool needs a connected account (Search Console, Google Analytics, Google Ads, Meta Ads).
availablebooleanWhether a page with this section shows data for this site now.
unavailable_reasonstring or nulltool_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

ArgumentTypeWhat it does
site_id (required)stringThe 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:

FieldTypeWhat it is
idstringThe report id.
namestringThe name of the report.
page_countintegerNumber of pages, without the cover page.
periodobject or nullThe months the report covers, YYYY-MM, to included; null when no period is set yet.
period.fromstringFirst month, YYYY-MM.
period.tostringLast month, YYYY-MM (the same as from for one month).
pdfobjectThe latest PDF of the report.
pdf.statusstringnone (never made), pending (being made, usually one to three minutes), done or failed.
pdf.periodobject or nullThe months of that PDF, {from, to}; null when none was made.
pdf.period.fromstringYYYY-MM.
pdf.period.tostringYYYY-MM.
pdf.requested_atstring or nullWhen it was started, ISO 8601 UTC; null when not known.
pdf.completed_atstring or nullWhen it was done or failed, ISO 8601 UTC; null while pending or not known.
created_atstring or nullWhen the report was made, ISO 8601 UTC; null for reports from before 13 November 2026.
updated_atstring or nullWhen 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

ArgumentTypeWhat it does
site_id (required)stringThe site: its id from list_sites, or the id in the app’s address.
report_id (required)stringThe 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:

FieldTypeWhat it is
idstringThe report id.
namestringThe name of the report.
periodobject or nullThe months the report covers, YYYY-MM, to included; null when no period is set yet.
period.fromstringFirst month, YYYY-MM.
period.tostringLast month, YYYY-MM (the same as from for one month).
pagesarrayThe pages in order, without the cover page.
pages[].positionintegerPage number in the report, 1 for the first page after the cover.
pages[].sectionstring or nullThe 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_labelstring or nullThe section in words, e.g. "Rank tracker: Keywords"; null without a section.
pages[].headingstringThe heading of the page.
pages[].textstringThe text under the heading.
pdfobjectThe latest PDF of the report.
pdf.statusstringnone (never made), pending (being made, usually one to three minutes), done or failed.
pdf.periodobject or nullThe months of that PDF, {from, to}; null when none was made.
pdf.period.fromstringYYYY-MM.
pdf.period.tostringYYYY-MM.
pdf.requested_atstring or nullWhen it was started, ISO 8601 UTC; null when not known.
pdf.completed_atstring or nullWhen it was done or failed, ISO 8601 UTC; null while pending or not known.
created_atstring or nullWhen the report was made, ISO 8601 UTC; null for reports from before 13 November 2026.
updated_atstring or nullWhen 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

ArgumentTypeWhat it does
site_id (required)stringThe site: its id from list_sites, or the id in the app’s address.
report_id (required)stringThe 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:

FieldTypeWhat it is
report_idstringThe report id.
readybooleanWhether the report has pages and every page is ok.
pages_okintegerNumber of pages that are ok.
pagesarrayPer page, in order.
pages[].positionintegerPage number, 1 for the first page after the cover.
pages[].sectionstring or nullThe section key; null without a section.
pages[].statusstringok, 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

ArgumentTypeWhat it does
site_id (required)stringThe site: its id from list_sites, or the id in the app’s address.
report_id (required)stringThe 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:

FieldTypeWhat it is
report_idstringThe report id.
statusstringnone (never made), pending (being made), done or failed (start it again with reports.generate).
periodobject or nullThe months of the PDF, {from, to}; null when none was made.
period.fromstringYYYY-MM.
period.tostringYYYY-MM.
requested_atstring or nullWhen it was started, ISO 8601 UTC; null when not known.
completed_atstring or nullWhen it was done or failed, ISO 8601 UTC; null while pending or not known.
download_urlstring or nullThe PDF, as a signed link that works without logging in; null unless status is done.
download_expires_atstring or nullUntil 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

ArgumentTypeWhat it does
site_id (required)stringThe site: its id from list_sites, or the id in the app’s address.
name (required)stringThe name of the report, at most 120 characters.
pageslist of objectThe 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.
periodobjectThe 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:

FieldTypeWhat it is
idstringThe report id.
namestringThe name.
periodobject or nullThe months the report covers, YYYY-MM, to included; null when no period is set yet.
period.fromstringFirst month, YYYY-MM.
period.tostringLast month, YYYY-MM (the same as from for one month).
pagesarrayThe pages in order, without the cover page.
pages[].positionintegerPage number in the report, 1 for the first page after the cover.
pages[].sectionstring or nullThe 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_labelstring or nullThe section in words, e.g. "Rank tracker: Keywords"; null without a section.
pages[].headingstringThe heading of the page.
pages[].textstringThe text under the heading.
pdfobjectThe latest PDF of the report.
pdf.statusstringnone (never made), pending (being made, usually one to three minutes), done or failed.
pdf.periodobject or nullThe months of that PDF, {from, to}; null when none was made.
pdf.period.fromstringYYYY-MM.
pdf.period.tostringYYYY-MM.
pdf.requested_atstring or nullWhen it was started, ISO 8601 UTC; null when not known.
pdf.completed_atstring or nullWhen it was done or failed, ISO 8601 UTC; null while pending or not known.
created_atstring or nullWhen the report was made, ISO 8601 UTC.
updated_atstring or nullWhen 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

ArgumentTypeWhat it does
site_id (required)stringThe site: its id from list_sites, or the id in the app’s address.
report_id (required)stringThe report: its id from reports.list.
namestringThe new name, at most 120 characters.
pageslist of objectThe 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.
periodobjectThe 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:

FieldTypeWhat it is
idstringThe report id.
namestringThe name.
periodobject or nullThe months the report covers, YYYY-MM, to included; null when no period is set yet.
period.fromstringFirst month, YYYY-MM.
period.tostringLast month, YYYY-MM (the same as from for one month).
pagesarrayThe pages in order, without the cover page.
pages[].positionintegerPage number in the report, 1 for the first page after the cover.
pages[].sectionstring or nullThe 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_labelstring or nullThe section in words, e.g. "Rank tracker: Keywords"; null without a section.
pages[].headingstringThe heading of the page.
pages[].textstringThe text under the heading.
pdfobjectThe latest PDF of the report.
pdf.statusstringnone (never made), pending (being made, usually one to three minutes), done or failed.
pdf.periodobject or nullThe months of that PDF, {from, to}; null when none was made.
pdf.period.fromstringYYYY-MM.
pdf.period.tostringYYYY-MM.
pdf.requested_atstring or nullWhen it was started, ISO 8601 UTC; null when not known.
pdf.completed_atstring or nullWhen it was done or failed, ISO 8601 UTC; null while pending or not known.
created_atstring or nullWhen the report was made, ISO 8601 UTC; null for reports from before 13 November 2026.
updated_atstring or nullWhen 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

ArgumentTypeWhat it does
site_id (required)stringThe site: its id from list_sites, or the id in the app’s address.
report_id (required)stringThe report: its id from reports.list.
to_site_idstringThe site to copy to (its id from list_sites); leave out for the same site. You need to be able to edit reports there.
namestringThe 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:

FieldTypeWhat it is
idstringThe id of the copy.
site_idstringThe site the copy is on.
namestringThe name of the copy.
periodobject or nullThe months the report covers, YYYY-MM, to included; null when no period is set yet.
period.fromstringFirst month, YYYY-MM.
period.tostringLast month, YYYY-MM (the same as from for one month).
pagesarrayThe pages in order, without the cover page.
pages[].positionintegerPage number in the report, 1 for the first page after the cover.
pages[].sectionstring or nullThe 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_labelstring or nullThe section in words, e.g. "Rank tracker: Keywords"; null without a section.
pages[].headingstringThe heading of the page.
pages[].textstringThe text under the heading.
pdfobjectThe latest PDF of the report.
pdf.statusstringnone (never made), pending (being made, usually one to three minutes), done or failed.
pdf.periodobject or nullThe months of that PDF, {from, to}; null when none was made.
pdf.period.fromstringYYYY-MM.
pdf.period.tostringYYYY-MM.
pdf.requested_atstring or nullWhen it was started, ISO 8601 UTC; null when not known.
pdf.completed_atstring or nullWhen it was done or failed, ISO 8601 UTC; null while pending or not known.
created_atstring or nullWhen the copy was made, ISO 8601 UTC.
updated_atstring or nullThe 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

ArgumentTypeWhat it does
site_id (required)stringThe site: its id from list_sites, or the id in the app’s address.
report_id (required)stringThe 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:

FieldTypeWhat it is
idstringThe id of the deleted report.
deletedbooleanAlways 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

ArgumentTypeWhat it does
site_id (required)stringThe site: its id from list_sites, or the id in the app’s address.
report_id (required)stringThe report: its id from reports.list.
periodobjectThe 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:

FieldTypeWhat it is
report_idstringThe report id.
statusstringpending.
periodobject or nullThe months of the PDF, {from, to}.
period.fromstringYYYY-MM.
period.tostringYYYY-MM.
requested_atstring or nullWhen it was started, ISO 8601 UTC.
completed_atstring or nullnull while pending.
download_urlstring or nullnull while pending; see reports.status.
download_expires_atstring or nullnull while pending.
White label

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.

API hubAll REST endpoints, keys and rate limits SEO MCP serverRead reports and SEO data in Claude or ChatGPT Search Console & GA4Pull the traffic numbers behind your report pages

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
Start your 14-day trial

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.