# Field Masks

The Ad Manager REST API uses field masks for partial reads and writes. This can
improve performance by limiting the amount of data transferred. Field masks
are represented by a comma separated list of field names. For example:

    startTime,endTime,targeting.geoTargeting

## Read masks

Read masks control which fields are present in an API response. You can set a
read mask on your request in two ways:

1. The `fields` query parameter:

       curl https://admanager.googleapis.com/v1/networks/123456/adUnits?fields=adUnits,nextPageToken,totalSize

2. The `X-Goog-FieldMask` HTTP header:

       curl -H "X-Goog-FieldMask: adUnits,nextPageToken,totalSize" \
           https://admanager.googleapis.com/v1/networks/123456/adUnits

> [!NOTE]
> **Note:** Both `camelCase` and `snake_case` are supported in field mask strings.

### Default read masks

Some API methods include a default field mask for fields that are expensive
to return. List methods are an example of this. By default, they don't include
the [`totalSize`](https://developers.google.com/ad-manager/api/beta/reference/rest/v1/networks.orders/list#response-body)
field.

These fields must be explicitly requested in the field mask either by name or by
using the `*` wildcard.

## Update masks

Update masks control which fields will be changed in an update (`PATCH`)
request. When an update mask is set, only the fields in the mask will be updated
regardless of which fields are set in the request body.

Update masks are set as query parameters. For example:

    curl -X PATCH https://admanager.googleapis.com/v1/networks/1234/order/4567?updateMask=displayName

## Field traversal

Field masks can specify fields within an entity using the `.` character for
traversal. This is the same syntax used by
[Filters](https://developers.google.com/ad-manager/api/beta/filters#traversal_operator).

Field masks are always relative to the response object. For example, a mask for
reading a `LineItem` might include `primaryGoal.units`. The corresponding mask
for [listing](https://developers.google.com/ad-manager/api/beta/reference/rest/v1/networks.orders.lineItems/list)
`LineItems` is `lineItems.primaryGoal.units`.

You can specify either a field as a whole, or one of its subfields. Both
`primaryGoal` and `primaryGoal.units` are valid.

This also applies to repeated fields. A `LineItem` field mask of
`creativePlaceholders.size` is valid and only includes the `size` field
for each `CreativePlaceholder`.

> [!NOTE]
> **Note:** Field masks don't permit accessing a particular element of a repeated field by index. This results in an `INVALID_ARGUMENT` error.

## Wildcards

> [!WARNING]
> **Warning:** Using a wildcard in an update mask is not forwards compatible. The wildcard will clear any fields that are unknown to your client.

Field masks support the `*` character which indicates all fields in the message.
The following examples demonstrate wildcard usage when [listing](https://developers.google.com/ad-manager/api/beta/reference/rest/v1/networks.orders/list)
`Orders`. This method has a [default read mask](https://developers.google.com/ad-manager/api/beta/field-masks#default_read_masks) that does
not include the `total_size` field.

| Example | Meaning |
|---|---|
| `*` | Includes all fields, including `total_size` |
| `orders` | Includes only the `orders` field and all its subfields |
| `orders.*` | Includes only the `orders` field and all its subfields |

## Invalid fields

If a field mask refers to a value that doesn't exist, the API will respond
with an `INVALID_ARGUMENT` error.