> ## Documentation Index
> Fetch the complete documentation index at: https://www.presolve.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Report definitions

> Execute saved reports, select authorized offices, and understand report-owner fields and filters.

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

```bash theme={null}
curl "https://www.presolve.com/api/v1/reports" \
  -H "x-api-key: YOUR_INTEGRATION_KEY"
```

`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

```bash theme={null}
curl -X POST "https://www.presolve.com/api/v1/reports/REPORT_ID/run" \
  -H "x-api-key: YOUR_INTEGRATION_KEY"
```

| Credential configuration | Scope when `organizationIds` is omitted |
| - | - |
| Non-HQ key | Key's organization |
| HQ key, child-organizations toggle off | Key's organization |
| HQ key, toggle on | HQ and authorized descendants, subject to current acting-attorney permissions |

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](/docs/authorization#hq-saved-report-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:

```bash theme={null}
curl -X POST \
  "https://www.presolve.com/api/v1/reports/REPORT_ID/run?organizationIds=HQ_ORGANIZATION_UUID,CHILD_ORGANIZATION_UUID" \
  -H "x-api-key: YOUR_INTEGRATION_KEY"
```

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](/docs/reporting/exports) are single-organization entity extracts; they do not reproduce a saved report's joins, filters, or HQ rollup automatically.

## Errors

| Status | Check |
| - | - |
| 400 | Organization ID syntax or incompatible report fields across selected offices |
| 401 | Credential type, secret, expiry, and revocation |
| 403 | `reports:read`, key scope toggle, acting attorney, current role permissions, and requested organization IDs |
| 404 | Report ID, deletion, ownership boundary, v1 API visibility, and sharing for a child report |
| 429 | Retry after the indicated delay |

Use the [report troubleshooting guide](/docs/reporting/troubleshooting) 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.