Find instances of resources (v3)

POST /v3/resources/search

Find IAM-enabled resources or storage and network resources that run on classic infrastructure in a specific account ID.

You must use `/v3/resources/search` when you need to fetch more than `10000` resource items. On the first call, the operation returns a live cursor on the data that you must use on all the subsequent calls to get the next batch of results until you get the empty result set.

To filter results, you can apply query strings following the Lucene query syntax.

By default, the fields that are returned for every resource are crn, name, family, type, and account_id. You can specify the subset of the fields you want in your request using the `fields` request body attribute. Set `"fields": ["*"]` to discover the complete set of fields which are available to request.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • global-search-tagging.resource.read

Request

Parameters

query

str

The Lucene-formatted query string. Default to '*' if not set.

fields

List[str]

The list of the fields returned by the search. By default, the returned fields are the `account_id`, `name`, `type`, `family`, and `crn`. For all queries, `crn` is always returned.

Constraints:

  • Min items: 1

search_cursor

str

An opaque cursor that is returned on each call and that must be set on the subsequent call to get the next batch of items. If the search returns no items, then the search_cursor is not present in the response.

Constraints:

  • Min length: 1

transaction_id

str

An alphanumeric string that can be used to trace a request across services. If not specified, it automatically generated with the prefix "gst-".

Constraints:

  • Min length: 1
  • Max length: 150
  • Pattern: /.*/

account_id

str

The account ID to filter resources.

Constraints:

  • Pattern: /^[a-zA-Z0-9.]+$|^[*]{1}$/

limit

int

The maximum number of hits to return. Defaults to 10.

Default: 10

timeout

int

A search timeout in milliseconds, bounding the search request to run within the specified time value and bail with the hits accumulated up to that point when expired. Defaults to the system defined timeout.

Default: 0

sort

List[str]

Comma separated properties names that are used for sorting.

is_deleted

str

Determines if deleted documents should be included in result set or not. Possible values are false (default), true or any. If false, only existing documents are returned; if true, only deleted documents are returned; If any, both existing and deleted documents are returned. (for administrators only).

Allowed values: true, false, any

Default: false

is_reclaimed

str

Determines if reclaimed documents should be included in result set or not. Possible values are false (default), true or any. If false, only not reclaimed documents are returned; if true, only reclaimed documents are returned; If any, both reclaimed and not reclaimed documents are returned.

Allowed values: true, false, any

Default: false

is_public

str

Determines if public resources should be included in result set or not. Possible values are false (default), true or any. If false, do not search public resources; if true, search only public resources; If any, search also public resources.

Allowed values: true, false, any

Default: false

impersonate_user

str

The user on whose behalf the search must be performed. Only a GhoST admin can impersonate a user, so be sure you set a GhoST admin IAM token in the Authorization header if you set this parameter. (for administrators only).

Constraints:

  • Pattern: /^.*-.*$/

can_tag

str

Determines if the result set must return the resources that the user can tag or the resources that the user can view (only a GhoST admin can use this parameter). If false (default), only resources user can view are returned; if true, only resources that user has permissions for tagging are returned (for administrators only).

Allowed values: true, false

Default: false

Response

200 - A result paging with the list of resources that match the provided filters.

search_cursor

string

The search cursor to use on all calls after the first one.

limit

integer

Value of the limit parameter specified by the user

items

array

The array of results. Each item represents a resource. For each resource, the requested `fields` are returned. If you did not set the `fields` request body parameter, then the `account_id`, `name`, `type`, `family`, and `crn` are returned. An empty array signals the end of the result set, which means there are no more results to fetch

400 - Bad Request

errors

array

List of errors that were encountered in processing the request

401 - Unauthorized / Wrong auth token type IAM / Auth token not valid

errors

array

List of errors that were encountered in processing the request

403 - Unauthorized operation

errors

array

List of errors that were encountered in processing the request

429 - Too Many Requests

500 - Internal Server Error / IAM not initialized / Malformed IAM credentials

errors

array

List of errors that were encountered in processing the request

502 - Search IAM error

errors

array

List of errors that were encountered in processing the request

default - System problem or unexpected error