# Remote API Reference
URL: https://pro.rv-grid.com/guides/pivot/server-side/remote-api-reference/
Source: src/content/docs/guides/pivot/server-side/remote-api-reference.mdx
Description: Technical specification for the RevoGrid Pivot remote analytical contract.
The Remote Pivot API is a transport-agnostic JSON contract that allows RevoGrid to communicate with analytical backends, OLAP cubes, or custom SQL planners.

## Load Request

The `PivotLoadRequest` is sent whenever the grid needs to materialize a visible window of analytical data.

### Root Properties

- `viewId`: Semantic identifier for the dataset (e.g., `sales_cube`).
- `fieldsVersion`: Version of the field registry used to resolve selectors.
- `loadOptions`: The analytical query definition.
- `viewport`: Request windows for row and column axes.
- `uiState`: Optional hints for engine-side formatting.

### Load Options

The `loadOptions` object defines the shape of the analytical query:

- `rows`: Array of group descriptors for the row axis.
- `columns`: Array of group descriptors for the column axis.
- `values`: Measures to aggregate.
- `filter`: Complex filter expression tree.
- `sort`: Sorting directives (can include sort-by-summary).
- `groupSummary`: Measures to calculate at every group level.

### Viewport

The `viewport` defines independent analytical windows:

- `rowAxis`: Contains `offset`, `limit`, and `expandedPaths`.
- `columnAxis`: Contains `offset`, `limit`, and `expandedPaths`.

Use analytical paths for expansion state, not visible row indexes.

### Normalization Limits

Before planning/execution, requests are typically normalized against backend limits (`PivotLimits`) to keep payloads and query complexity bounded.

Common limits include:

- `maxRowWindowSize`: Maximum allowed `rowAxis.limit`.
- `maxColumnWindowSize`: Maximum allowed `columnAxis.limit`.
- `maxExpandedPaths`: Maximum number of expansion paths per axis.
- `maxExpansionDepth`: Maximum hierarchy depth of a single expansion path.
- `maxDrilldownLimit`: Maximum page size for drilldown requests.

For `maxExpansionDepth`, depth is the number of path segments. Example: `['Region', 'Country', 'City']` has depth `3`.

## Load Response

`PivotLoadResponse` returns only the data needed for the current visible window.

### Root Properties

- `data`: Array of row records (expected to have `__rowPath` and `__columnPath`).
- `summary`: Optional grand-total or pinned rows.
- `rowAxis`: Window metadata for the row axis.
- `columnAxis`: Window metadata for the column axis.
- `groupAggregates`: Optional grouped-row measures.
- `meta`: Diagnostic metadata.

Important response metadata:

- `cacheStatus`: 'hit', 'miss', 'warm', or 'bypass'.

## Axis Metadata

Both `rowAxis` and `columnAxis` use the same metadata structure.

| Field | Role | Description |
| :--- | :---: | :--- |
| `paths` | Required (Columns) | Array of analytical paths used to generate headers. |
| `totalCount` | Required (Rows) | Total members on server. Required for row-axis scrollbars and pagination. |

## Drilldown

Drilldown uses `PivotDrilldownRequest` and `PivotDrilldownResponse`.

The request identifies a visible summary cell by:

- `rowPath`
- `columnPath`
- optional `dataIndex`

The backend should reuse the same analytical filter context as the Pivot request, then return matching fact rows with pagination.

## UI State Hints

`uiState` hints allow the backend to optimize its output format:

- `rowHeaderLayout`: 'tree' or 'flat'.
- `showTotalsPrior`: Placement of subtotals.
- `collapsedByDefault`: Initial hierarchy state.
