System parameters

Google's API platform provides a set of common functionality to all Google APIs built using the platform. In order to use and control such functionality, the platform pre-defines a special set of request parameters called system parameters . These parameters are available across all Google REST APIs and gRPC APIs. A system parameter can be specified either using an HTTP query parameter or an HTTP header. For Google gRPC APIs, only HTTP headers are supported.

Most users won't need to use these parameters directly. However, they are often used by Google-provided client libraries . If you need to write custom code to access Google APIs directly, the system parameters can be useful in cases such as controlling JSON pretty-printing or specifying API Keys.

HTTP Mapping

For HTTP requests, system parameters are sent as URL query parameters or HTTP request headers. For example, if you have a system parameter $foo , it's sent as ?$foo=xxx in the URL, or ?%24foo=xxx if URL-encoded. See the table below for details.

gRPC Mapping

For gRPC requests, system parameters are sent as HTTP request headers with keys in lowercase. See the table below for details.

Definitions

The following table lists all system parameters and their definitions.

URL Query Parameter

HTTP/gRPC Header

Description

Authorization

Authentication credentials. See Authentication overview for details.

$alt ,
alt

Alternative response format. Supported values are json (default), media , proto , sse (JSON streams).

$.xgafv

JSON error format. Supported values are 1 , 2 (default). The error format 1 should only be used by Google API Client Libraries .

$callback ,
callback

JSONP callback parameter.

$ct

Content-Type

HTTP Content-Type request header override.

$fields ,
fields

X-Goog-FieldMask

FieldMask used for response filtering. If empty, all fields should be returned unless documented otherwise.

X-HTTP-Method-Override

The intended HTTP method for the request. Some network proxies don't accept all HTTP methods.

$key ,
key

X-Goog-Api-Key

Google API key. See https://cloud.google.com/docs/authentication/api-keys for details.

passwd ,
password

Reserved to prevent putting passwords in URLs.

$prettyPrint ,
prettyPrint

Pretty-print JSON response. Supported values are true (default), false .

quotaUser

X-Goog-Quota-User

A pseudo user identifier for charging per-user quotas. If not specified, the authenticated principal is used. If there is no authenticated principal, the client IP address will be used. When specified, a valid API key with service restrictions must be used to identify the quota project. Otherwise, this parameter is ignored.

$outputDefaults

Force to output proto default values for JSON responses.

$unique

Unique query parameter to disable request caching.

X-Goog-Api-Client

API client identification. The value is a space-separated list of NAME "/" SEMVER strings, where the NAME should only contain lowercase letters, digits, and "-", and the SEMVER should be a semantic version string. For example: X-Goog-Api-Client: python/3.5.0 grpc-google-pubsub-v1/0.1.0-beta2 linux/2.7.0.

X-Goog-Request-Reason

Contains a reason for making the request, which is intended to be recorded in audit logging. An example reason would be a support-case ticket number. For audit logs, the characters in the reason determine whether the reason is base64 encoded before being attached to the log entry. Reasons that include only letters, digits, and spaces are retained in plain text. Reasons that include other characters are base64 encoded.

$userProject

X-Goog-User-Project

A caller-specified project for quota and billing purposes. The caller must have serviceusage.services.use permission on the project.

X-Server-Timeout

Timeout (in seconds, float value) for the server to finish processing the request. This system param only applies to REST APIs for which client-side timeout is not applicable.

x-goog-request-params

Passing additional parameters for gRPC requests. The value must be URL query string encoded (e.g., key1=value1&key2=value2 ).

The specific keys and values supported within this header are dependent on the individual Google API service and method being called. There is no single, universal set of parameters for this header. Always consult the documentation for the specific API you are interacting with to determine which parameters are supported or required.

Common uses include:

Routing Information: For regionalized services, this header often carries parameters to help GFEs route the request to the correct regional backend. This frequently involves keys matching resource name parts (e.g., name=projects/my-proj/locations/us-central1 , parent=projects/my-proj/locations/us-central1 ) or explicit location parameters (e.g., grpc-location=locations/us-central1 ).
API-Specific Functionality: For example, the BigQuery Storage Write API uses the write_stream parameter within this header for non-US multi-region gRPC calls (e.g., x-goog-request-params: write_stream=projects/myproject/datasets/myds/tables/mytable/streams/mystream ).

Example:
x-goog-request-params: name=projects/my-project/locations/us-central1&foo=bar

Changelog

2026-06 Updated documentation for x-goog-request-params .
2021-11 Published documentation for x-goog-request-params .
2021-02 Published documentation for quotaUser .
2020-07 Deprecated OAuth 2.0 query parameters.
2019-10 Introduced X-Server-Timeout system parameter.
2017-10 Introduced X-Goog-User-Project system parameter.