Instâncias de relatório

List report instances

reports.instances.list

Lists the organization's report instances (each one a report for a period, generated from a template, draft or finalized), newest first, paginated by cursor. A workspace keeps the instances of all its accounts: filter one account with target_org_id, and draft/finalized with status. Items are summaries (template, period, account, PDF and portal state, page and block counts); fetch the pages with reports.instances.get. Each period comes with start_date and end_date when it is fixed (null for a named period, resolved when it renders). Members and viewers only see the accounts assigned to them; that filter and status read further until the page is full (up to 600 instances per call): keep following next_cursor while has_more is true. Requires view access to Reports.

Escopo

reports:read

Permissão

Ver o módulo

Tool do MCP

reports_instances_listNa superfície completa; na compacta, mb_execute_operation com id: "reports.instances.list".

Custo declarado: até 202 leituras e 0 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

curl "https://api.mb-suite.com/v1/reports/instances" \
  -H "Authorization: Bearer $MB_API_KEY"

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

curl "https://api.mb-suite.com/v1/reports/instances" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Get a report instance with its pages

reports.instances.get

Returns one report instance with all its pages (sections) and blocks (including the AI text generated for it), its period, data source mapping, account, PDF state (has_pdf, pdf_job_status queued|running|failed) and portal state. Download the PDF with reports.instances.pdf_url. Not found if it does not exist in the organization; forbidden if it belongs to an account not assigned to you. Requires view access to Reports.

Escopo

reports:read

Permissão

Ver o módulo

Tool do MCP

reports_instances_getNa superfície completa; na compacta, mb_execute_operation com id: "reports.instances.get".

Custo declarado: até 1 leituras e 0 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

curl "https://api.mb-suite.com/v1/reports/instances/{instance_id}" \
  -H "Authorization: Bearer $MB_API_KEY"

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

curl "https://api.mb-suite.com/v1/reports/instances/{instance_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Generate a report instance from a template

reports.instances.generate

Generates a draft report instance for a period from a template: the organization's own (template_source=ORGANIZATION), a published one of the parent workspace (INHERITED) or a published system template (SYSTEM). Send the period (date_range: preset, config, label), optionally the account it is for (target_org_id, a child of the workspace) and the data_source_mapping (slot or platform of the template → data source id of that account, from reports.data_sources.list with the same target_org_id). With target_org_id the instance is kept in the workspace and its data sources are checked against that account's connections (own or inherited from the workspace), never the workspace's alone: an id the account does not have is 400 data_source_not_linked. The media plan of the period is linked automatically. AI text blocks are generated only from the MB Suite screen, with the AI credits of the person who generates the report: when the credit pool does not cover them, the instance is generated anyway and those blocks are left empty with ai_error_code (ai_credits_exhausted, ai_personal_limit or payment_required). Through the API, the MCP or MIA they are created empty, ready to generate from the editor. The period (date_range) is a preset ({preset: last_month}), fixed days ({start_date, end_date}) or the stored form (preset, config, label); the server fills in what is missing. Then export it with reports.instances.export_pdf. Fires reports.instance.generated. Requires edit access to Reports.

Escopo

reports:write

Permissão

Editar no módulo

Tool do MCP

reports_instances_generateNa superfície completa; na compacta, mb_execute_operation com id: "reports.instances.generate".

Eventos que pode emitir

reports.instance.generated

Custo declarado: até 106 leituras e 1 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

curl -X POST "https://api.mb-suite.com/v1/reports/instances/generate" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "template_id": "TEMPLATE_ID",
  "date_range": {}
}'

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

curl -X POST "https://api.mb-suite.com/v1/reports/instances/generate" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "template_id": "TEMPLATE_ID",
  "date_range": {}
}'

Create a blank report instance

reports.instances.create

Creates an empty draft report instance (one page, no blocks) for a period, to build by hand with reports.instances.update: title (default «Reporte sin título» in the caller's language), period (date_range: a preset, start_date and end_date, or the stored form), optionally the account it is for (target_org_id), its data source mapping and the platforms it may use. To start from a template use reports.instances.generate. Returns the instance id. Requires edit access to Reports.

Escopo

reports:write

Permissão

Editar no módulo

Tool do MCP

reports_instances_createNa superfície completa; na compacta, mb_execute_operation com id: "reports.instances.create".

Custo declarado: até 2 leituras e 1 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

curl -X POST "https://api.mb-suite.com/v1/reports/instances" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "date_range": {}
}'

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

curl -X POST "https://api.mb-suite.com/v1/reports/instances" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "date_range": {}
}'

Update a draft report instance

reports.instances.update

Updates fields of a draft report instance: title, description, subtitle, pages (send the full sections array), period (date_range), cover page, table of contents, module pages and their own periods (module_date_ranges), theme, accent color, labels, allowed platforms, data source mapping and linked media plan (selected_media_plan_id). null removes the optional ones (cover page, theme, accent color, media plan, module periods). Finalized instances are read-only (409 report_instance_finalized): duplicate them to edit a copy. New platform data sources must be connected to the account whose data the report reads; new block types, metrics, dimensions and presets are checked (report_block_type_unknown, unknown_metric, unknown_dimension, preset_unknown), labels must exist (label_unknown, reports.labels.list) and the media plan too (media_plan_not_found). Fields go inside updates. Returns the updated instance. Requires edit access to Reports.

Escopo

reports:write

Permissão

Editar no módulo

Tool do MCP

reports_instances_updateNa superfície completa; na compacta, mb_execute_operation com id: "reports.instances.update".

Custo declarado: até 2 leituras e 1 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

curl -X PATCH "https://api.mb-suite.com/v1/reports/instances/{instance_id}" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "updates": {}
}'

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

curl -X PATCH "https://api.mb-suite.com/v1/reports/instances/{instance_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "updates": {}
}'

Finalize a report instance without a PDF

reports.instances.finalize

Locks a draft report instance (status finalized, read-only) without generating its PDF; exporting the PDF also finalizes it. Finalizing one that is already finalized changes nothing (changed: false). Fires reports.instance.finalized. Requires edit access to Reports.

Escopo

reports:write

Permissão

Editar no módulo

Tool do MCP

reports_instances_finalizeNa superfície completa; na compacta, mb_execute_operation com id: "reports.instances.finalize".

Eventos que pode emitir

reports.instance.finalized

Custo declarado: até 1 leituras e 1 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

curl -X POST "https://api.mb-suite.com/v1/reports/instances/{instance_id}/finalize" \
  -H "Authorization: Bearer $MB_API_KEY"

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

curl -X POST "https://api.mb-suite.com/v1/reports/instances/{instance_id}/finalize" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Duplicate a report instance

reports.instances.duplicate

Copies a report instance into a new draft titled '<title> (Copia)' (the suffix in the caller's language: (Copia), (Copy) or (Cópia)) with new page and block ids, keeping its period and template. To reuse it for another account of the workspace, send target_org_id with that account's data_source_mapping (its media plan is re-matched). Works on finalized instances too (it is how they are edited). Returns the new instance id. Requires edit access to Reports.

Escopo

reports:write

Permissão

Editar no módulo

Tool do MCP

reports_instances_duplicateNa superfície completa; na compacta, mb_execute_operation com id: "reports.instances.duplicate".

Custo declarado: até 104 leituras e 1 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

curl -X POST "https://api.mb-suite.com/v1/reports/instances/{instance_id}/duplicate" \
  -H "Authorization: Bearer $MB_API_KEY"

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

curl -X POST "https://api.mb-suite.com/v1/reports/instances/{instance_id}/duplicate" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Delete a report instance

reports.instances.delete

Deletes a report instance; it stays 30 days in the trash (platform.trash.restore brings it back with its PDF, which is kept in storage). If it was published to the client portal it disappears from there too. Owners and admins delete any instance; anyone else with edit access to Reports only the ones they created (created_by), so whoever generates a report to export its PDF can remove it afterwards; any other is 403 role_required, also on the dry run. Outside the screen it needs a dry run and a confirm_token, or a key with deletion enabled.

Com uma API key, este DELETE roda direto: o registro fica 30 dias na lixeira e a resposta traz o seu trash_item_id. Com um token OAuth, e pelo MCP, pede dry_run → confirm_token.

Escopo

reports:write e «Permitir exclusões» (reports:delete no OAuth)

Permissão

Editar no módulo

Tool do MCP

reports_instances_deleteNa superfície completa; na compacta, mb_execute_operation com id: "reports.instances.delete".

Custo declarado: até 1 leituras e 2 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

curl -X DELETE "https://api.mb-suite.com/v1/reports/instances/{instance_id}" \
  -H "Authorization: Bearer $MB_API_KEY"

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

curl -X DELETE "https://api.mb-suite.com/v1/reports/instances/{instance_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Delete many report instances

reports.instances.bulk.delete

Deletes up to 500 report instances; each goes to the 30-day trash. Ids that do not exist or belong to an account not assigned to you are skipped; count says how many were deleted. Owners and admins only. Outside the screen it always needs a dry run (which lists what will be deleted) and its confirm_token.

Pede confirmação: primeiro dry_run: true (prévia e confirm_token, válido por 10 minutos e por uma única execução), depois o mesmo corpo com confirm_token. Em algumas poucas, só com certos dados: a descrição diz quando. Por que e como: Prévia e confirmação.

Escopo

reports:write e «Permitir exclusões» (reports:delete no OAuth)

Permissão

Editar no módulo · Só owner, admin

Tool do MCP

reports_instances_bulk_deleteNa superfície completa; na compacta, mb_execute_operation com id: "reports.instances.bulk.delete".

Custo declarado: até 500 leituras e 1000 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

curl -X POST "https://api.mb-suite.com/v1/reports/instances/bulk/delete" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "instance_ids": [
    "INSTANCE_ID"
  ],
  "dry_run": true
}'

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

curl -X POST "https://api.mb-suite.com/v1/reports/instances/bulk/delete" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "instance_ids": [
    "INSTANCE_ID"
  ],
  "dry_run": true
}'

Generate the PDF of a report instance

reports.instances.export_pdf

Starts the PDF of a report instance in the background (status queued): the render reads every platform of its blocks live and takes up to two minutes; when it ends, reports.pdf.ready (or reports.pdf.failed) fires and the instance is finalized. If the PDF already exists it returns status ready with a signed download link valid for one hour. A job already running returns queued again. Generating the PDF of a draft finalizes it, so it needs edit access; a finalized one only needs view access. Daily PDF quota: each new render counts 1 against the pdf external quota of the organization that pays the call (by default 50 a day on a trial, 300 starter, 1,000 growth, 2,500 scale, 5,000 enterprise; it resets at 00:00 UTC); the MB-Quota-External-Platform (pdf), MB-Quota-External-Limit and MB-Quota-External-Remaining headers say what is left. Returning a PDF that already exists or a job already running does not use it up, but once the quota is used up this call fails with 429 quota_exceeded (details.quota.type external) until the reset, except for a job already running. To wait for a PDF poll reports.instances.get (pdf_job_status, has_pdf) or the reports.pdf.ready webhook, and download it with reports.instances.pdf_url: neither counts against the PDF quota. In the practice organization (test keys) nothing is rendered and no platform is read: the job finishes at once with a one-page stand-in PDF that says so (the instance is finalized and has_pdf is true, so the first poll of reports.instances.get finds it and reports.instances.pdf_url downloads it); the response carries simulated: true, and the call uses none of the PDF quota and fires no notification or webhook. With Google Ads, Google Business Profile, LinkedIn, TikTok or YouTube, their terms limit it through the API and the MCP: what they do not allow answers 403 platform_terms_restricted (the permissions guide lists what each platform allows).

Escopo

reports:write

Permissão

Ver o módulo

Tool do MCP

reports_instances_export_pdfNa superfície completa; na compacta, mb_execute_operation com id: "reports.instances.export_pdf".

Eventos que pode emitir

reports.pdf.readyreports.pdf.failedreports.instance.finalized

Custo declarado: até 1 leituras e 2 escritas por chamada (contam na cota diária). Usa uma plataforma externa (pdf): conta na cota de operações externas.

Parâmetros

Resposta

Erros

Exemplo

curl -X POST "https://api.mb-suite.com/v1/reports/instances/{instance_id}/pdf" \
  -H "Authorization: Bearer $MB_API_KEY"

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar. Na prática esta operação é simulada: nada é enviado e a resposta traz simulated: true.

curl -X POST "https://api.mb-suite.com/v1/reports/instances/{instance_id}/pdf" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Get a download link for the PDF of a report instance

reports.instances.pdf_url

Returns a signed link to download the PDF of a report instance, valid for one hour (expires_at), with its file name and when it was generated. Ask for a new link each time: links are never stored. 404 report_pdf_not_found if the PDF was never generated (start it with reports.instances.export_pdf) and report_pdf_missing if the file is no longer in storage. Requires view access to Reports. With Google Ads, Google Business Profile, LinkedIn, TikTok or YouTube, their terms limit it through the API and the MCP: what they do not allow answers 403 platform_terms_restricted (the permissions guide lists what each platform allows).

Escopo

reports:read

Permissão

Ver o módulo

Tool do MCP

reports_instances_pdf_urlNa superfície completa; na compacta, mb_execute_operation com id: "reports.instances.pdf_url".

Custo declarado: até 1 leituras e 0 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

curl "https://api.mb-suite.com/v1/reports/instances/{instance_id}/pdf" \
  -H "Authorization: Bearer $MB_API_KEY"

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

curl "https://api.mb-suite.com/v1/reports/instances/{instance_id}/pdf" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Publish a report to the account's client portal

reports.instances.publish_to_portal

Publishes a finalized report instance of an account to that account's Client Portal (published: true), or removes it from there (published: false). Only finalized instances generated for an account can be published (409 otherwise). Setting the state it already has changes nothing (changed: false). Publishing fires reports.instance.published. Requires edit access to Reports.

Escopo

reports:write

Permissão

Editar no módulo

Tool do MCP

reports_instances_publish_to_portalNa superfície completa; na compacta, mb_execute_operation com id: "reports.instances.publish_to_portal".

Eventos que pode emitir

reports.instance.published

Custo declarado: até 1 leituras e 1 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

curl -X POST "https://api.mb-suite.com/v1/reports/instances/{instance_id}/portal" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "published": true
}'

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

curl -X POST "https://api.mb-suite.com/v1/reports/instances/{instance_id}/portal" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "published": true
}'

Save a report instance as a template

reports.instances.save_as_template

Creates a published template of the organization from the structure of a report instance: same pages and blocks with new ids, without the generated content, and each data source turned into a slot (ds_1, ds_2…) so the template can be used for any account. Returns the template id and fires reports.template.published. Requires edit access to Reports.

Escopo

reports:write

Permissão

Editar no módulo

Tool do MCP

reports_instances_save_as_templateNa superfície completa; na compacta, mb_execute_operation com id: "reports.instances.save_as_template".

Eventos que pode emitir

reports.template.published

Custo declarado: até 1 leituras e 1 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

curl -X POST "https://api.mb-suite.com/v1/reports/instances/{instance_id}/save-as-template" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "title": "TITLE"
}'

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

curl -X POST "https://api.mb-suite.com/v1/reports/instances/{instance_id}/save-as-template" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "title": "TITLE"
}'