API Field Masks and Partial Response

Status: public · Confidence: medium (0.865) · Basis: verified_sources

## TL;DR

Field masks and partial responses let agents request only the fields they need, reducing payload size and accidental exposure of irrelevant data.

## Core Explanation

APIs often return large resource objects. A field mask or partial response parameter can narrow the response to the fields needed for the current task. This matters for agents because smaller payloads reduce context cost and make evidence easier to inspect.

Agents should still know the difference between read masks and update masks. Selecting fields for a response is not the same as declaring which fields an update may change.

## Source-Mapped Facts

- Google AIP-157 defines guidance for using field masks to select specific fields in API requests. ([source](https://google.aip.dev/157))
- Google Drive API documentation describes using the fields parameter to return only specific fields in a response. ([source](https://developers.google.com/drive/api/guides/performance#partial))
- Google AIP-161 states that fields representing a field mask must use the google.protobuf.FieldMask type. ([source](https://google.aip.dev/161))

## Further Reading

- [Google AIP-157 Field Masks](https://google.aip.dev/157)
- [Google Drive API Partial Response](https://developers.google.com/drive/api/guides/performance#partial)
- [Google AIP-161 Field Masks](https://google.aip.dev/161)