This guide describes how to use the API Explorer to try out Monitoring API methods. API Explorer is a widget attached to the REST API reference page for a method. It appears as a panel with the title Try this API. The following screenshot shows the panel as it appears for a method with only one parameter, name:
The API Explorer is an excellent way to try out methods in the Monitoring API without having to write any code. The widget presents a form showing the parameters for each method. Fill in the form, click the Execute button, and see the results.
You can also hide the widget by clicking the close button at the top of the panel, or expand it to full screen by clicking the fullscreen button.
Try It! buttons
Through the documentation, you will see Try It! buttons like the following accompanying some examples:
Clicking the button brings up the API Explorer on the proper reference
page and populates the fields as appropriate to the example. You will have
to edit some of the fields to match your own project, such as the value for
See Tips for additional information about avoiding and fixing errors.
Accessing the API Explorer
The API Explorer is attached to the reference page for each REST API
method. To find the widget, go to the reference page for a method, for example,
the reference page for
Executing a minimal request
Most methods have some required parameters and some optional ones. The required ones are marked with a red bar until they are filled. You can execute a minimal request by supplying only the required arguments.
metricDescriptors.list method returns descriptors for all of the
available metric types in a project. The only required field is the
name field. To retrieve this list for your project, supply the name
of your project for name, using the form
Click the button below to try it out, but before you click Execute button
on the form, you need to change
[PROJECT_ID] to the identfier for your
The results of the method invocation appear in a box under the Execute
button. Typically, the box will have a green header with the HTTP status
200 in it, indicating the request succeeded. The results of the
invocation are in the box:
If the header is red and contains an HTTP failure code, the box contains the error message. See Tips for some pointers on resolving errors.
Supplying additional parameters
The list of parameters you see depends on the method to which the
API Explorer widget is attached. The
has more than just the name parameter, but name is the only required
When you provide only the project name, you get all the metric descriptors available in your project, and there are a lot of them. You can use the optional filter parameter to restrict the retrieval to a smaller set.
For example, fill in the following fields on the
Substitute your project ID for
[PROJECT_ID], but supply the other value as
Executing this request returns only the descriptors for metric types whose names
Using fields to limit output further
By default, the set of parameters that API Explorer shows corresponds to the parameters of the associated method. However, the API Explorer widget also has a set of extra fields that are not available via the method itself.
These parameters are hidden under the toggle Show standard parameters, which appears above the Authentication section:
Click this toggle to expose the extra widget parameters. Click Hide standard parameters to hide them from view.
The most useful of these standard parameters is the fields parameter, which lets you select the fields in the returned output that you want to see. This is very useful in the API Explorer panel, where the output is displayed in a box. There is often a lot of output to scroll through.
For example, listing the descriptors for metrics ending with
still returns a lot of information. If all you are interested in is the
name of the metric type and its description, you can use the fields
field to specify those fields only.
To see the difference, fill in the following fields on the
Substitute your project ID for
[PROJECT_ID], but supply the other values
- name, as before:
- filter, as before:
Executing this request returns only the
type (short name) of each metric
description. The following is part of the output:
Remember to change
Do not forget to replace
[PROJECT_ID] with your project's ID. If you forget,
you get the following result:
Problems with the values
Here are some issues to watch for when using the API Explorer forms. These mistakes might cause errors or might be accepted but be treated like spelling errors in the API method:
- Do not use quotation marks around field values of any type.
- Be sure to quote strings appearing inside filters. Use double quotation
") and not apostrophes (
'). See Supplying additional parameters for an example.
- Do not use backslashes or URL-encoding in form fields. If needed, URL-encoding is performed on the field values when you execute the method.
- Look at the value in the result box after executing the call. You might notice the problem there.
- You might want to supply a value for the pageSize field, such as
2. This limits the amount of data that is returned as you debug your API call.
Bookmark URLs for debugging
After you get the output you want, bookmark the API Explorer URL. When you want to run the method again, paste the URL into your browser. You see the form already populated with your values. Make any necessary changes to the parameters, and click Execute to run the method again.
There is an Authentication section on the API Explorer page, above the Execute button. You typically do not need to change anything here.
The default authentication mechanism is
Google OAuth 2.0.
There is also a Show scopes toggle in the Authentication section. This shows you which Compute Engine scopes you have available. By default, all available scopes are enabled.
See Access Control for more information on these concepts.
If you still have trouble, see
Troubleshooting the Monitoring API.