Skip to main content
A saved report defines columns, filters, grouping, and sorting. The v1 API executes that definition; it does not accept arbitrary SQL, replacement filters, or new columns in the request. Use an integration API key with reports:read. The legacy /api/reports/{reportId} endpoint uses a separate reporting credential. Switching the URL alone does not migrate a legacy integration.

​
Discover a report

GET /api/v1/reports lists API-visible reports owned by the key’s organization. GET /api/v1/reports/{reportId} returns one such report’s metadata, without rows. Both remain single-organization endpoints, including for HQ keys. An HQ key can run a shared, API-visible child report by its known ID even though that report is absent from the HQ key’s list and its metadata endpoint returns 404. Get the ID from the report owner or an authorized user of the reporting workspace. API-visible (apiVisible) is the v1 publication setting. It is separate from application sharing (isShared) and legacy API sharing (isApiShared). If a report works in the viewer or legacy API but v1 returns 404, ask the report administrator to verify v1 publication specifically. Do not assume the legacy sharing control enables v1.

​
Execute the default scope

The toggle is labeled Current organization + child organizations, stored as reportIncludeChildOrganizations, and defaults to on for existing and new keys. Default HQ rollups need an acting attorney with the required HQ and data permissions. Missing configuration or insufficient permissions returns 403 rather than silently reducing the request to one office.

​
Select offices explicitly

Pass comma-separated organization UUIDs in the query string:
Replace the placeholders with actual UUIDs. Every ID must be within the key’s authorized report scope. The parameter narrows scope; it cannot override a disabled toggle, missing permissions, or an unrelated organization’s boundary. Unauthorized IDs return 403. Malformed or empty lists return 400. To request only one office, pass just that office’s ID. A child key cannot use this parameter to reach its parent or siblings.

​
Shared child reports and custom fields

Running a child-owned report from HQ does not clone it or move its ownership. The saved report’s owner supplies the field definitions; the authorized execution scope determines which organizations supply rows. For example, a custom intake field such as employer name is interpreted using the report owner’s field definition. The engine checks compatibility across requested offices. An office without its own definition is allowed only after a stored-answer check confirms there are no answers for that accessor; those values remain blank. Historical answers without a definition cause a compatibility error, since their meaning cannot be established. Conflicting types, storage mappings, or enum meanings return 400 instead of silently restricting the result to the report owner. Saved filters still apply across the selected offices. A report filtered to Converted does not also include Matched–Direct merely because the key is HQ or the organization scope is wider. An authorized editor must update that report’s filter if the desired business definition includes both statuses. NSA records require the acting attorney’s current NSA access as well as applicable case and HQ permissions. HQ status alone does not grant NSA access. NSA-only restrictions are preserved. Cross-office compatibility checks for child-owned runtime fields support at most 100 organizations per execution. Narrow organizationIds for larger hierarchies. Catalog checks run at most four offices concurrently.

​
Formats, limits, and retries

  • JSON is the default. Send Accept: text/csv for CSV.
  • Results are capped at 10,000 rows. Check truncated: true in JSON or X-Result-Truncated: true for CSV.
  • Report execution has a dedicated 5 runs/minute per key limit in addition to the shared sensitive tier. Respect Retry-After on 429.
  • Execution is a read even though it uses POST. It does not require X-Idempotency-Key.
For a truncated hierarchy report, narrow the selected offices or saved report filters and design non-overlapping extracts. Export jobs are single-organization entity extracts; they do not reproduce a saved report’s joins, filters, or HQ rollup automatically.

​
Errors

Use the report troubleshooting guide before changing filters or credentials. Built-in lead and matter status columns used only for display may have different available options and customized system-status labels in each office. Multi-organization rows show the record’s own status label qualified by its organization, such as Appeal Filed (Washington). Filter choices list each organization’s label for the same stored status key. Selecting a status does not select an organization; use the organization selector to narrow the scope. Status filters, sorting, grouping, calculations, and charts still require compatible definitions; custom-field compatibility checks remain unchanged.