reports:read scope:
- Saved reports — execute a report definition someone in the org has already built and flagged for API access. Synchronous, capped at 10,000 rows, ideal for dashboards and scheduled pulls of curated views. See Report definitions.
- Export jobs — enqueue an asynchronous bulk export of an entity family (leads or cases) and download the finished file via a presigned link. Capped at 100,000 rows per job (exceeding it fails the job — narrow the filters and split the extract), ideal for full syncs and warehouse loads. See Exports.
Which one to use
If a report run returns
truncated: true, narrow its office scope or saved filters. Export jobs can serve larger single-organization entity extracts, but do not automatically reproduce saved-report filters, joins, or HQ rollups.
Access model
- Everything here requires the
reports:readscope. - Only report definitions the organization has explicitly flagged API-visible are listed or runnable — the API cannot see, enumerate, or execute any other saved report. Confirm v1 publication with the report administrator; it is separate from legacy API sharing.
- Report execution carries no query material in the request: the API runs the saved definition as-is. There is no ad-hoc query endpoint on this surface.
HQ reporting
The integration key setting Current organization + child organizations defaults to on. For HQ saved-report execution, it uses the acting attorney’s current reporting, hierarchy, and data permissions. ExplicitorganizationIds narrows that scope; the setting does not expand other v1 endpoints. Shared child reports retain their owner and field definitions.
Start with Organizations, HQ, and permissions, then Report execution. For missing offices, NSA records, status-filter differences, or 404s, use Troubleshooting reports.