Instancias de reporte

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.

Alcance

reports:read

Permiso

Ver el módulo

Tool del MCP

reports_instances_listEn la superficie completa; en la compacta, mb_execute_operation con id: "reports.instances.list".

Costo declarado: hasta 202 lecturas y 0 escrituras por llamada (cuentan en el cupo diario).

Parámetros

Respuesta

Errores

Ejemplo

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

Probar con tu API key de prueba

Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes 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.

Alcance

reports:read

Permiso

Ver el módulo

Tool del MCP

reports_instances_getEn la superficie completa; en la compacta, mb_execute_operation con id: "reports.instances.get".

Costo declarado: hasta 1 lecturas y 0 escrituras por llamada (cuentan en el cupo diario).

Parámetros

Respuesta

Errores

Ejemplo

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

Probar con tu API key de prueba

Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes 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.

Alcance

reports:write

Permiso

Editar en el módulo

Tool del MCP

reports_instances_generateEn la superficie completa; en la compacta, mb_execute_operation con id: "reports.instances.generate".

Eventos que puede emitir

reports.instance.generated

Costo declarado: hasta 106 lecturas y 1 escrituras por llamada (cuentan en el cupo diario).

Parámetros

Respuesta

Errores

Ejemplo

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": {}
}'

Probar con tu API key de prueba

Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes 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.

Alcance

reports:write

Permiso

Editar en el módulo

Tool del MCP

reports_instances_createEn la superficie completa; en la compacta, mb_execute_operation con id: "reports.instances.create".

Costo declarado: hasta 2 lecturas y 1 escrituras por llamada (cuentan en el cupo diario).

Parámetros

Respuesta

Errores

Ejemplo

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": {}
}'

Probar con tu API key de prueba

Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes 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.

Alcance

reports:write

Permiso

Editar en el módulo

Tool del MCP

reports_instances_updateEn la superficie completa; en la compacta, mb_execute_operation con id: "reports.instances.update".

Costo declarado: hasta 2 lecturas y 1 escrituras por llamada (cuentan en el cupo diario).

Parámetros

Respuesta

Errores

Ejemplo

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": {}
}'

Probar con tu API key de prueba

Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes 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.

Alcance

reports:write

Permiso

Editar en el módulo

Tool del MCP

reports_instances_finalizeEn la superficie completa; en la compacta, mb_execute_operation con id: "reports.instances.finalize".

Eventos que puede emitir

reports.instance.finalized

Costo declarado: hasta 1 lecturas y 1 escrituras por llamada (cuentan en el cupo diario).

Parámetros

Respuesta

Errores

Ejemplo

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

Probar con tu API key de prueba

Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes 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.

Alcance

reports:write

Permiso

Editar en el módulo

Tool del MCP

reports_instances_duplicateEn la superficie completa; en la compacta, mb_execute_operation con id: "reports.instances.duplicate".

Costo declarado: hasta 104 lecturas y 1 escrituras por llamada (cuentan en el cupo diario).

Parámetros

Respuesta

Errores

Ejemplo

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

Probar con tu API key de prueba

Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes 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.

Con una API key, este DELETE se ejecuta directo: el registro queda 30 días en la papelera y la respuesta trae su trash_item_id. Con un token OAuth, y por el MCP, pide dry_run → confirm_token.

Alcance

reports:write y «Permitir eliminar» (reports:delete en OAuth)

Permiso

Editar en el módulo

Tool del MCP

reports_instances_deleteEn la superficie completa; en la compacta, mb_execute_operation con id: "reports.instances.delete".

Costo declarado: hasta 1 lecturas y 2 escrituras por llamada (cuentan en el cupo diario).

Parámetros

Respuesta

Errores

Ejemplo

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

Probar con tu API key de prueba

Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes 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.

Pide confirmación: primero dry_run: true (vista previa y confirm_token, que vale 10 minutos y una sola vez), después el mismo cuerpo con confirm_token. En unas pocas, solo con ciertos datos: la descripción dice cuándo. Por qué y cómo: Vista previa y confirmación.

Alcance

reports:write y «Permitir eliminar» (reports:delete en OAuth)

Permiso

Editar en el módulo · Solo owner, admin

Tool del MCP

reports_instances_bulk_deleteEn la superficie completa; en la compacta, mb_execute_operation con id: "reports.instances.bulk.delete".

Costo declarado: hasta 500 lecturas y 1000 escrituras por llamada (cuentan en el cupo diario).

Parámetros

Respuesta

Errores

Ejemplo

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
}'

Probar con tu API key de prueba

Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes 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).

Alcance

reports:write

Permiso

Ver el módulo

Tool del MCP

reports_instances_export_pdfEn la superficie completa; en la compacta, mb_execute_operation con id: "reports.instances.export_pdf".

Eventos que puede emitir

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

Costo declarado: hasta 1 lecturas y 2 escrituras por llamada (cuentan en el cupo diario). Toca una plataforma externa (pdf): cuenta en el cupo de operaciones externas.

Parámetros

Respuesta

Errores

Ejemplo

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

Probar con tu API key de prueba

Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes reiniciar. En la práctica esta operación se simula: no sale nada y la respuesta trae 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).

Alcance

reports:read

Permiso

Ver el módulo

Tool del MCP

reports_instances_pdf_urlEn la superficie completa; en la compacta, mb_execute_operation con id: "reports.instances.pdf_url".

Costo declarado: hasta 1 lecturas y 0 escrituras por llamada (cuentan en el cupo diario).

Parámetros

Respuesta

Errores

Ejemplo

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

Probar con tu API key de prueba

Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes 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.

Alcance

reports:write

Permiso

Editar en el módulo

Tool del MCP

reports_instances_publish_to_portalEn la superficie completa; en la compacta, mb_execute_operation con id: "reports.instances.publish_to_portal".

Eventos que puede emitir

reports.instance.published

Costo declarado: hasta 1 lecturas y 1 escrituras por llamada (cuentan en el cupo diario).

Parámetros

Respuesta

Errores

Ejemplo

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
}'

Probar con tu API key de prueba

Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes 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.

Alcance

reports:write

Permiso

Editar en el módulo

Tool del MCP

reports_instances_save_as_templateEn la superficie completa; en la compacta, mb_execute_operation con id: "reports.instances.save_as_template".

Eventos que puede emitir

reports.template.published

Costo declarado: hasta 1 lecturas y 1 escrituras por llamada (cuentan en el cupo diario).

Parámetros

Respuesta

Errores

Ejemplo

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

Probar con tu API key de prueba

Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes 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"
}'