Ad hoc reports

List ad hoc report PDFs

reports.adhoc.list

Lists the ad hoc report PDFs generated in the organization (PDFs made on the spot from a template or an editable report, without a report instance), newest first, paginated by cursor: title, period, account, template and when the file expires (12 months). Get a download link with reports.adhoc.pdf_url. Members and viewers only see the accounts assigned to them; that filter and target_org_id read further until the page is full. Requires view access to Reports.

Scope

reports:read

Permission

View the module

MCP tool

reports_adhoc_listOn the full surface; on the compact one, mb_execute_operation with id: "reports.adhoc.list".

Declared cost: up to 202 reads and 0 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

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

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

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

Get a fresh download link for an ad hoc PDF

reports.adhoc.refresh_url

Signs a new 7-day download link for the PDF of an ad hoc report and stores it on the record, while the file is still in storage (12 months after it was generated). 409 adhoc_pdf_expired once it expired; 404 adhoc_pdf_missing if the file is gone. 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).

Scope

reports:write

Permission

View the module

MCP tool

reports_adhoc_refresh_urlOn the full surface; on the compact one, mb_execute_operation with id: "reports.adhoc.refresh_url".

Declared cost: up to 1 reads and 1 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/reports/adhoc/{adhoc_report_id}/refresh-url" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X POST "https://api.mb-suite.com/v1/reports/adhoc/{adhoc_report_id}/refresh-url" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Get the download link of an ad hoc report PDF

reports.adhoc.pdf_url

Returns a signed download link (valid one hour) for the PDF of an ad hoc report, while the file is still in storage (12 months after it was generated), without changing anything: a read-only credential can use it. 409 adhoc_pdf_expired once it expired; 404 adhoc_pdf_missing if the file is gone. 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).

Scope

reports:read

Permission

View the module

MCP tool

reports_adhoc_pdf_urlOn the full surface; on the compact one, mb_execute_operation with id: "reports.adhoc.pdf_url".

Declared cost: up to 1 reads and 0 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

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

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

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

Delete an ad hoc report PDF

reports.adhoc.delete

Deletes an ad hoc report from the history together with its PDF file. It does not go to the trash: the file is removed from storage, so there would be nothing to restore. Owners and admins only. Outside the screen it always needs a dry run and its confirm_token.

Needs confirmation: first dry_run: true (preview and confirm_token, valid 10 minutes and for one run), then the same body with confirm_token. In a few operations only with certain data: the description says when. Why and how: Dry run and confirm_token.

Scope

reports:write and “Allow deletions” (reports:delete in OAuth)

Permission

Edit in the module · Only owner, admin

MCP tool

reports_adhoc_deleteOn the full surface; on the compact one, mb_execute_operation with id: "reports.adhoc.delete".

Declared cost: up to 1 reads and 1 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X DELETE "https://api.mb-suite.com/v1/reports/adhoc/{adhoc_report_id}" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "dry_run": true
}'

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X DELETE "https://api.mb-suite.com/v1/reports/adhoc/{adhoc_report_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "dry_run": true
}'