Stay organized with collections
Save and categorize content based on your preferences.
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:
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
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:
Field masks can specify fields within an entity using the . character for
traversal. This is the same syntax used by
Filters.
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 listingLineItems 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.
Wildcards
Field masks support the * character which indicates all fields in the message.
The following examples demonstrate wildcard usage when listingOrders. This method has a default read mask 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.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-28 UTC."],[[["\u003cp\u003eThe Ad Manager REST API utilizes field masks, represented as comma-separated field names, for partial data reads and writes to enhance performance.\u003c/p\u003e\n"],["\u003cp\u003eRead masks, set via the \u003ccode\u003efields\u003c/code\u003e query parameter or \u003ccode\u003eX-Goog-FieldMask\u003c/code\u003e HTTP header, dictate which fields are returned in API responses, with default masks applied to some methods for efficiency.\u003c/p\u003e\n"],["\u003cp\u003eUpdate masks, specified as query parameters, control which fields are modified during update requests, ensuring only masked fields are affected regardless of the request body content.\u003c/p\u003e\n"],["\u003cp\u003eField masks support traversal using the \u003ccode\u003e.\u003c/code\u003e character and wildcards for selecting specific fields or all fields within an entity, although wildcard use in update masks is not recommended for forward compatibility.\u003c/p\u003e\n"],["\u003cp\u003eInvalid fields in a field mask will trigger an \u003ccode\u003eINVALID_ARGUMENT\u003c/code\u003e error response from the API.\u003c/p\u003e\n"]]],["The Ad Manager REST API uses field masks to specify data in API requests, improving performance. Read masks, set via `fields` query parameters or `X-Goog-FieldMask` headers, control which fields are returned in responses; some methods have default masks. Update masks, set as query parameters, dictate which fields are modified in `PATCH` requests. Field traversal uses `.` notation, and the `*` wildcard includes all fields. Invalid fields in masks will cause an error.\n"],null,["# Field Masks\n\nThe Ad Manager REST API uses field masks for partial reads and writes. This can\nimprove performance by limiting the amount of data transferred. Field masks\nare represented by a comma separated list of field names. For example: \n\n startTime,endTime,targeting.geoTargeting\n\nRead masks\n----------\n\nRead masks control which fields are present in an API response. You can set a\nread mask on your request in two ways:\n\n1. The `fields` query parameter:\n\n curl https://admanager.googleapis.com/v1/networks/123456/adUnits?fields=adUnits,nextPageToken,totalSize\n\n2. The `X-Goog-FieldMask` HTTP header:\n\n curl -H \"X-Goog-FieldMask: adUnits,nextPageToken,totalSize\" \\\n https://admanager.googleapis.com/v1/networks/123456/adUnits\n\n| **Note:** Both `camelCase` and `snake_case` are supported in field mask strings.\n\n### Default read masks\n\nSome API methods include a default field mask for fields that are expensive\nto return. List methods are an example of this. By default, they don't include\nthe [`totalSize`](/ad-manager/api/beta/reference/rest/v1/networks.orders/list#response-body)\nfield.\n\nThese fields must be explicitly requested in the field mask either by name or by\nusing the `*` wildcard.\n\nUpdate masks\n------------\n\nUpdate masks control which fields will be changed in an update (`PATCH`)\nrequest. When an update mask is set, only the fields in the mask will be updated\nregardless of which fields are set in the request body.\n\nUpdate masks are set as query parameters. For example: \n\n curl -X PATCH https://admanager.googleapis.com/v1/networks/1234/order/4567?updateMask=displayName\n\nField traversal\n---------------\n\nField masks can specify fields within an entity using the `.` character for\ntraversal. This is the same syntax used by\n[Filters](/ad-manager/api/beta/filters#traversal_operator).\n\nField masks are always relative to the response object. For example, a mask for\nreading a `LineItem` might include `primaryGoal.units`. The corresponding mask\nfor [listing](/ad-manager/api/beta/reference/rest/v1/networks.orders.lineItems/list)\n`LineItems` is `lineItems.primaryGoal.units`.\n\nYou can specify either a field as a whole, or one of its subfields. Both\n`primaryGoal` and `primaryGoal.units` are valid.\n\nThis also applies to repeated fields. A `LineItem` field mask of\n`creativePlaceholders.size` is valid and only includes the `size` field\nfor each `CreativePlaceholder`.\n| **Note:** Field masks don't permit accessing a particular element of a repeated field by index. This results in an `INVALID_ARGUMENT` error.\n\nWildcards\n---------\n\n| **Warning:** Using a wildcard in an update mask is not forwards compatible. The wildcard will clear any fields that are unknown to your client.\n\nField masks support the `*` character which indicates all fields in the message.\nThe following examples demonstrate wildcard usage when [listing](/ad-manager/api/beta/reference/rest/v1/networks.orders/list)\n`Orders`. This method has a [default read mask](#default_read_masks) that does\nnot include the `total_size` field.\n\n| Example | Meaning |\n|------------|--------------------------------------------------------|\n| `*` | Includes all fields, including `total_size` |\n| `orders` | Includes only the `orders` field and all its subfields |\n| `orders.*` | Includes only the `orders` field and all its subfields |\n\nInvalid fields\n--------------\n\nIf a field mask refers to a value that doesn't exist, the API will respond\nwith an `INVALID_ARGUMENT` error."]]
