adsense-management

AdSense Management API organizes publishers' resources under an account hierarchy. Most operations operate on named resources that follow a path format (for example accounts/{account}, accounts/{account}/adclients/{adclient}, accounts/{account}/adclients/{adclient}/adunits/{adunit}). Understanding that hierarchy and which resource name each operation expects is the key to progressing from discovery to action.

Key entities and how they relate

Account is the top-level owner. Many collections are scoped to an account (alerts, reports, payments, sites, policy issues, child accounts). Account resource names look like accounts/{account}.
AdClient is scoped under an account: accounts/{account}/adclients/{adclient}. Ad clients own ad units, custom channels, and URL channels.
AdUnit lives under an ad client: accounts/{account}/adclients/{adclient}/adunits/{adunit}. Ad units are the actual ad placements for which you can retrieve ad code (getAdcode) and list linked custom channels.
CustomChannel lives under an ad client: accounts/{account}/adclients/{adclient}/customchannels/{customchannel}. Custom channels can be linked to ad units; the API exposes listing of those links but not a separate “link” create endpoint in this surface.
UrlChannel lives under an ad client and is used for URL-level reporting: accounts/{account}/adclients/{adclient}/urlchannels.
SavedReport is a named saved report under an account: accounts/{account}/reports/{report}. Saved reports can be retrieved and executed.
Report and CsvReport are generated from an account; both require reporting parameters (metrics required). Generated CSV responses arrive as raw HttpBody.
Other account-scoped resources: alerts, payments, sites, policyIssues, adBlockingRecoveryTag.

Remember: most path parameters are full resource names (the slash-separated strings above), not plain numeric IDs. Passing just the numeric ID where the API expects the full resource name is the most common source of confusion.

Entry points — what to call first

To discover what account to operate on, call the account listing endpoint. The API exposes a top-level accounts listing that returns account resource names (use that to pick accounts/{account}).
Once an account resource name is available, list ad clients for that account to get adclient resource names: call the ad clients list under accounts/{account}. Many ad-client-scoped operations require the ad client resource name as parent.
To enumerate actual inventory, list ad units under an ad client (adunits.list) and list custom channels under the same ad client (customchannels.list). Use the returned resource names for subsequent calls (for example adunits.getAdcode or customchannels.patch).
Saved reports live under an account: call saved reports list to discover reports/{report} names to run with reports.saved.generate.

Common tasks and the operation sequences to perform them

These are the sequences that map directly to typical user requests.

Find which accounts and ad clients a publisher has

Call the accounts list to retrieve accounts/{account} names.
For a chosen account, call ad clients list with parent = accounts/{account} to retrieve ad client resource names.

Inspect inventory for a specific ad client (ad units, custom channels, URL channels)

With parent = accounts/{account}/adclients/{adclient}, call adunits.list, customchannels.list, and urlchannels.list to enumerate inventory. Each list may return nextPageToken; if present, request the next page with the same parameters and that token.

Create an ad unit under an ad client

Call the ad unit create operation with parent = accounts/{account}/adclients/{adclient} and the ad unit body. The response body is the created ad unit resource (includes its full resource name to use in later calls).
To retrieve the rendering code for an ad unit, call the ad unit adcode getter with name = the ad unit resource name (format: accounts/{account}/adclients/{adclient}/adunits/{adunit}).

Manage custom channels

Create a custom channel by calling custom channels create with parent = accounts/{account}/adclients/{adclient} and the custom channel body.
Update a custom channel by calling the patch operation with name = the full custom channel resource name and set updateMask to the comma-separated fields to change. If updateMask is empty, the patch behaves like a full update.
Delete a custom channel by calling delete with name = the full custom channel resource name.
To see what ad units are linked to a custom channel, call the custom channel’s listLinkedAdUnits with parent = accounts/{account}/adclients/{adclient}/customchannels/{customchannel}. To see what custom channels an ad unit belongs to, call the ad unit’s listLinkedCustomChannels with parent = accounts/{account}/adclients/{adclient}/adunits/{adunit}.
- Note: the API surface provided here exposes listing of links. There is no separate link-creation operation in this set—links are managed either when creating/updating channels in the hosting product or via a different endpoint not shown here.

Run an ad performance/earnings report

For ad-hoc reports, call reports.generate with account = the account resource name and required metrics. Provide date range via the split query fields startDate.year/month/day and endDate.year/month/day or use the named dateRange shortcuts. Provide dimensions and filters as needed.
For CSV output, call reports.generateCsv with the same parameters; the response body is a raw HttpBody (CSV). The CSV endpoint supports a larger maximum number of rows.
To run a saved report by name, call reports.saved.generate with name = accounts/{account}/reports/{report}. You can also retrieve a saved report definition with reports.getSaved before executing it.

Check account-level state

Alerts: call alerts.list with parent = account resource name. You can supply languageCode to localize messages.
Payments: call payments.list with parent = account resource name to retrieve payments history.
Sites: call sites.list with parent = account resource name to enumerate registered sites.
Policy issues: call policyIssues.list with parent = account resource name to see flagged items; call policyIssues.get with a name of the form accounts/{account}/policyIssues/{policy_issue} to inspect a single issue.
Ad Blocking Recovery Tag: call the ad blocking recovery tag getter with name = accounts/{account} to retrieve the tag.

Reporting specifics and practical constraints

metrics is required for reports.generate / reports.generateCsv. The call will fail (or be meaningless) without specifying at least one metric.
Date parameters are provided as separate startDate.year, startDate.month, startDate.day (and the same for endDate). The API also supports named dateRange enumerations for common spans such as LAST_7_DAYS.
filters are strings following the reporting filtering syntax and are combined as logical AND: every provided filter must match for a row to be included.
The default and maximum row limits differ between endpoints: the standard report generation has a default limit (and a documented max for that endpoint), while the CSV report endpoint supports a larger maximum (notably up to 1,000,000 rows). Truncation for the structured reports.generate response is detectable by comparing the number of returned rows to total_matched_rows in the response; the CSV endpoint returns raw data and will simply be truncated if over the CSV limit.
Use orderBy with a + or - prefix to control column sort direction. If no prefix is provided, ascending is assumed.
reportingTimeZone can be set when generating reports; if omitted the account time zone applies.

Non-obvious parameter/name patterns and pitfalls

Many operations use parent, some use account or name. The string expected is almost always the full resource name (for example accounts/12345 or accounts/12345/adclients/pub-67890), not a bare numeric ID. Verify the returned resource's name field and pass that exact value when a later call asks for the resource name.
customchannels.patch requires the resource name in the name path—and the operation's path comment may read "Output only" for the name field in resource definitions. Treat it as the identifier: supply the full resource name and use updateMask to perform partial updates; if updateMask is omitted the patch acts as a full replacement.
List endpoints accept pageSize up to 10000 and return nextPageToken when results span pages. If pageToken is required to fetch further pages, the list response contains it.
Several list endpoints will silently coerce pageSize values above the maximum to the maximum. Assume a 10000 ceiling for ad clients, ad units, custom channels, url channels, policy issues, and similar lists.
getAdcode requires the exact ad unit resource name. Passing only adunit or adclient without the full path will not work.
The CSV endpoints return HttpBody; treat the body as raw CSV content rather than structured JSON.

Typical responses that indicate success or next steps

Creation calls return the created resource in the response body with its name field populated. Use that name for subsequent operations that require that resource.
Ad unit ad code retrieval returns an ad code resource containing the markup/snippet to place on pages. That is the canonical source for the ad HTML/JS for an ad unit.
Report generation returns either a structured ReportResult (for JSON) with headers, rows, and total_matched_rows, or a raw HttpBody (for CSV). If total_matched_rows is larger than the number of rows returned, the report is truncated; adjust limit or reduce the query scope.

Short checklist before calling any operation

Confirm which full resource name string the operation requires (accounts/{account} vs accounts/{account}/adclients/{adclient} vs accounts/{account}/adclients/{adclient}/adunits/{adunit}) and pass that exact string.
For reports, ensure metrics is provided and dates are set via the split date fields or dateRange shortcuts.
For patch/update, set updateMask to limit changes; otherwise expect a full update behavior.
For list endpoints expect nextPageToken when results exceed a single page and use the returned token with the same query parameters to request the next page.

These patterns cover the common, high-value tasks publishers ask for: enumerating accounts and inventory, creating ad units, fetching ad code, managing custom channels, and producing reports. When an operation expects a resource name, prefer the name values returned by prior list or create calls rather than constructing paths manually from numeric IDs.