Skip to main content
Pulumi logo Pulumi logo
25.6K Contact us Sign in Dashboard Get started
  1. Docs
  2. Reference
  3. REST API Docs
  4. Resource Search

Resource Search

This Pulumi Cloud feature is available in the Team, Enterprise, and Business Critical editions.
    Resource Search lets you find and filter resources managed by Pulumi across your organization. The Resource Search API allows you to query resources using structured filters and retrieve detailed resource metadata.

    Graph Query

    ▼
    Preview. This endpoint is in preview and may change without notice.
    POST /api/insights/{orgName}/graph/query

    Executes a graph selection query over the organization’s resource graph, returning the matching subgraph or flat aggregation buckets. Results are trimmed to the caller’s visible stacks and accounts.

    Request Parameters

    • orgName string path required
      The organization name

    Request Body

    Schema: GraphQueryRequest
    • scope GraphQueryScope optional
      Bounds where the anchor set is selected. Traversal may walk beyond the scope; only RBAC visibility and depth/fanout caps bound traversal. Omitted means all visible resources in the organization.
    • anchor GraphQueryAnchor required
      The anchor (zero-hop) node selection.
    • traverse array[GraphTraverseStep] optional
      Ordered, typed, depth-bounded traversal steps applied from the anchor set. Each step’s result becomes the frontier for the next step.
    • aggregate GraphQueryAggregate optional
      Flat aggregation over the anchor node set (group-by plus metrics). Only valid when ’traverse’ is empty; aggregation fused with traversal is not supported.
    • return GraphQueryReturn optional
      Shapes the response: which named frontiers to return, which node fields to project, and whether to include evidence paths.
    • page GraphQueryPage optional
      Pagination controls: the page size and the continuation token to resume from. To bound the anchor set itself rather than the page, use anchor.limit.

    Responses

    200 OK
    Schema: GraphQueryResponse
    • nodes array[GraphNode] required
      This page’s slice of the selected nodes (id-ordered), from the frontiers named in return.select plus any nodes referenced by returned paths.
    • ↳ id string required
      Stable node identifier: the Pulumi URN for IaC resources, the Insights URN for discovered resources, or ‘stack://’ for stacks. A stack’s id is not the spelling a selector uses: scope.stacks and a stack anchor’s name predicate both take the org-free ‘project/stack’ form, and both reject the org-qualified form.
    • ↳ nodeType enum required
      The node type.
      Values: resource, stack
    • ↳ frontier array[string] required
      Names of the selected frontiers this node belongs to (‘anchor’ or traversal step aliases).
    • ↳ urn string optional
      The resource URN. Absent for stack nodes.
    • ↳ type string optional
      The resource type token. Absent for stack nodes.
    • ↳ stack string optional
      The Pulumi stack this node belongs to, or that it represents for a stack node. Absent on a resource discovered by a cloud scan.
    • ↳ project string optional
      The Pulumi project this node belongs to, or that it represents for a stack node. Absent on a resource discovered by a cloud scan.
    • ↳ account string optional
      The Insights account a discovered resource was found in, as the complete account name including any ‘/’-separated hierarchy.
    • ↳ fields map[string]string optional
      Additional projected fields requested via return.fields, plus engine-provided provenance fields where available.
    • ↳ fieldsUnavailable boolean optional
      True when this node carries no indexed document, so none of the fields requested in return.fields could be evaluated on it. Absent unless return.fields was requested.
    • edges array[GraphEdge] required
      The typed edges revealed by this page: every edge whose higher-id endpoint first appears on this page. Both endpoints are among the nodes returned by this page or an earlier one — process pages cumulatively. A drain over changing data may not be complete.
    • ↳ id string required
      Stable edge identifier, unique within the response.
    • ↳ from string required
      The source node id.
    • ↳ to string required
      The destination node id.
    • ↳ type string required
      The edge type, for example ‘provided_by’ or ‘inferred_reference’.
    • paths array[GraphPath] optional
      Evidence paths showing how the query reached its results. Present only when return.paths is true. One path per node of the final traversal frontier, not necessarily the shortest route.
    • ↳ nodes array[string] required
      Node ids along the path, in traversal order. Every id named here is present among the response’s nodes once the page containing it has been retrieved.
    • ↳ edges array[string] required
      Edge ids along the path, in traversal order. One fewer entry than nodes.
    • aggregations GraphAggregations required
      Aggregation buckets. Empty unless the query included an aggregate clause.
    • ↳ buckets array[GraphAggregationBucket] required
      The aggregation buckets.
    • pageInfo GraphPageInfo required
      Result-set pagination information.
    • ↳ continuationToken string optional
      Opaque keyset token for the next page, omitted rather than null when no pages remain. Pass it back as page.continuationToken.
    • ↳ resultCount integer required
      The number of nodes (or aggregation buckets) returned on this page.
    • meta GraphQueryMeta required
      Result metadata, including whether anything clipped the underlying result.
    • ↳ resultMode enum required
      Result fidelity: whether an engine cap or a partial search-backend response clipped the underlying result. Treat ’truncated’ as disqualifying for any question whose answer depends on completeness, such as an absence check.
      Values: exact, truncated
    • ↳ schemaVersion string required
      The dated revision of the graph contract this query was evaluated against, for example ‘2026-07-29’. While the graph query API is in preview the contract can change.
    • ↳ visibility enum optional
      Whether the caller’s permissions limited what the traversal could see. Always present for traversal queries; absent for aggregations, which are always scoped to the caller’s permissions. Anchor selection is likewise caller-scoped and not reported here. Independent of resultMode, which reports engine-side clipping.
      Values: complete, trimmed
    Errors: 400 Invalid selector 402 The context API requires an Enterprise subscription or similar 404 The context API is off for this installation, it has no search cluster, or the path matches no route 409 Self-hosted installation whose license does not enable the context API 503 The entitlement lookup or the resource graph was unreachable and the request can be retried

    Get Graph Schema

    ▼
    Preview. This endpoint is in preview and may change without notice.
    GET /api/insights/{orgName}/graph/schema

    Returns the vocabulary and engine limits that graph query selectors are validated against. With ‘Accept: text/markdown’, returns a self-contained guide to composing selectors instead, kept current with this deployment’s validator.

    Request Parameters

    • orgName string path required
      The organization name

    Responses

    200 OK
    Schema: GraphSchemaResponse
    • schemaVersion string required
      The dated revision of the graph contract this response describes, for example ‘2026-07-29’.
    • nodeTypes array[GraphSchemaNodeType] required
      The selectable node types.
    • ↳ name enum required
      The node type name, usable as anchor.nodeType.
      Values: resource, stack
    • ↳ selectableFields array[string] required
      Field names usable in anchor match.fields predicates for this node type. This is the widest of the three vocabularies.
    • ↳ projectableFields array[string] required
      Field names usable in return.fields projections, and — for node types that carry a document — in a traverse step’s target.match. Naming a field outside this list returns a 400.
    • ↳ groupByFields array[string] required
      Field names usable in aggregate.groupBy for this node type. Naming a field outside this list returns a 400. Empty for node types that cannot be aggregated.
    • ↳ identity string required
      How a node of this type is identified in a response and how a selector names one. For stacks the two spellings differ, and the field lists cannot say so: they name fields, never formats.
    • ↳ fieldValues map[string]array required
      For the subset of selectableFields whose values are a fixed, closed set defined in code, the values themselves, keyed by field name. Absence from this map means no fixed set is advertised, not that the field has none; where such a field also appears in groupByFields, aggregate on it to discover its values.
    • edgeTypes array[GraphSchemaEdgeType] required
      The traversable edge types.
    • ↳ name string required
      The edge type name, usable in traverse[].edgeTypes.
    • ↳ from enum required
      The node type at the edge’s source.
      Values: resource, stack
    • ↳ to enum required
      The node type at the edge’s destination.
      Values: resource, stack
    • ↳ asserts string required
      What the presence of this edge asserts about the two nodes it connects, and which end is which.
    • ↳ singleHop boolean required
      Whether this edge type is walked in exactly one hop. A traverse step naming one must leave depth unset or set depth.max to 1.
    • ↳ directions array[string] required
      The traversal directions this edge type can be walked in, listed in the order ‘in’, ‘out’, ‘both’. A traverse step naming a direction absent from this list is rejected.
    • ↳ basis enum required
      How edges of this type are produced.
      Values: declared, inferred
    • metricOps array[string] required
      The aggregate metric operations usable in aggregate.metrics[].op. A selector naming an operation absent from this list is rejected rather than answered with a differently-computed metric.
    • limits GraphSchemaLimits required
      Engine limits applied to every query.
    • ↳ maxDepth integer required
      Maximum traversal depth per step. A selector limit: a step whose depth.max exceeds it is rejected.
    • ↳ maxTraverseSteps integer required
      Maximum number of traversal steps per query. A selector limit: a query with more steps is rejected.
    • ↳ maxScopeAccounts integer required
      Maximum number of cloud accounts scope.accounts may list. A selector limit: a longer list is rejected.
    • ↳ maxScopeStacks integer required
      Maximum number of stacks scope.stacks may list. A selector limit: a longer list is rejected.
    • ↳ maxGroupByFields integer required
      Maximum number of fields aggregate.groupBy may name. A selector limit: naming more is rejected.
    • ↳ maxAnchorNodes integer required
      Maximum number of anchor nodes one query resolves, and the upper bound on anchor.limit. When more nodes match, the result is clipped and reported as truncated - except under a selector that also traverses, where an engine-imposed clip is rejected instead. Also a selector limit: a match.fields[…].in list longer than this is rejected.
    • ↳ maxFanout integer required
      Maximum new nodes discovered per traversal level. A result limit.
    • ↳ maxNodes integer required
      Maximum total nodes held by one query evaluation. A result limit.
    • ↳ maxPaths integer required
      Maximum evidence paths returned. A result limit.
    • ↳ maxRecordedCrossings integer required
      Maximum number of edge crossings a traversal step records while walking. A result that reaches this bound is returned with resultMode ’truncated’ rather than rejected.
    • ↳ maxPageSize integer required
      Maximum page size. Applied silently rather than as a rejection or a truncation: a page.pageSize above this value is reduced to it.

    Get Org Resource Search Query

    ▼
    Deprecated. Use GetOrgResourceSearchV2Query instead.
    GET /api/orgs/{orgName}/search/resources

    Searches for resources within an organization. Deprecated: use GetOrgResourceSearchV2Query for improved search functionality.

    Request Parameters

    • orgName string path required
      The organization name
    • collapse boolean query optional
      Collapse results to show one entry per stack instead of per resource
    • cursor string query optional
      Cursor for paginated results
    • facet array query optional
      Facet filters to apply
    • groupBy string query optional
      Group results by this field
    • page integer query optional
      Page number for pagination
    • properties boolean query optional
      Include resource properties in search results (may increase response size)
    • query string query optional
      Search query string
    • size integer query optional
      Number of results to return
    • sort array query optional
      Sort order for results
    • top integer query optional
      Number of top aggregation buckets to return

    Responses

    200 OK
    Schema: ResourceSearchResult
    • total integer optional
      The total number of matching resources.
    • resources array[ResourceResult] optional
      The list of matching resource results.
    • ↳ created string optional
      The ISO 8601 timestamp when the resource was first indexed.
    • ↳ custom boolean optional
      Whether this is a custom resource managed by a provider plugin.
    • ↳ delete boolean optional
      Whether this resource is pending deletion.
    • ↳ dependencies array[string] optional
      URNs of resources that this resource depends on.
    • ↳ external boolean optional
      Whether the lifecycle of this resource is not managed by Pulumi.
    • ↳ id string optional
      The provider-assigned resource ID.
    • ↳ matches map[string]array optional
      Matched search terms mapped to their highlighted values.
    • ↳ modified string optional
      The ISO 8601 timestamp when the resource was last updated in the index.
    • ↳ module string required
      The module that contains this resource.
    • ↳ name string optional
      The name of the resource.
    • ↳ package string required
      The package that provides this resource.
    • ↳ parent_urn string optional
      The URN of the parent resource, if any.
    • ↳ pending string optional
      The pending operation on this resource, if any (e.g. creating, updating, deleting).
    • ↳ project string optional
      The project that contains this resource.
    • ↳ protected boolean optional
      Whether this resource is protected from deletion.
    • ↳ provider_urn string optional
      The URN of the provider for this resource.
    • ↳ stack string optional
      The stack that contains this resource.
    • ↳ type string optional
      The full type token of the resource (e.g. aws:s3/bucket:Bucket).
    • ↳ urn string optional
      The URN uniquely identifying this resource within a stack.
    • ↳ teams array[string] optional
      The teams that have access to this resource.
    • ↳ properties object optional
      The resource’s input/output properties as a JSON object. Only populated when explicitly requested.
    • ↳ metadata object optional
      Additional metadata associated with the resource.
    • ↳ category string optional
      The category of the resource.
    • ↳ account string optional
      The Insights account name that discovered or manages this resource.
    • ↳ dependents array[string] optional
      URNs of resources that depend on this resource.
    • ↳ managed string optional
      What manages this resource’s lifecycle: ‘Pulumi’ for a resource in a Pulumi IaC stack, ‘Terraform’ / ‘CloudFormation’ / ‘ARM’ for one discovered under another IaC tool, and ‘Other’ for one Insights scanning found under no known tool.
    • ↳ fingerprint string optional
      A fingerprint uniquely identifying this resource’s state.
    • ↳ sourceCount integer optional
      The number of sources for this resource.
    • aggregations map[string]Aggregation optional
      Aggregation buckets for faceted search.
    • pagination ResourceSearchPagination optional
      Pagination links for navigating through results.
    • ↳ previous string optional
      Link to the previous page of results.
    • ↳ next string optional
      Link to the next page of results.
    • ↳ cursor string optional
      An opaque cursor for resuming pagination.
    Errors: 400 invalid groupBy field 422 search cluster is unreachable

    Get Resource Dashboard Aggregations

    ▼
    GET /api/orgs/{orgName}/search/resources/dashboard

    GetResourceDashboardAggregations returns aggregated resource data for display on organization dashboard cards, including resource counts grouped by package and other dimensions.

    Request Parameters

    • orgName string path required
      The organization name

    Responses

    200 OK
    Schema: ResourceSearchResult
    • total integer optional
      The total number of matching resources.
    • resources array[ResourceResult] optional
      The list of matching resource results.
    • ↳ created string optional
      The ISO 8601 timestamp when the resource was first indexed.
    • ↳ custom boolean optional
      Whether this is a custom resource managed by a provider plugin.
    • ↳ delete boolean optional
      Whether this resource is pending deletion.
    • ↳ dependencies array[string] optional
      URNs of resources that this resource depends on.
    • ↳ external boolean optional
      Whether the lifecycle of this resource is not managed by Pulumi.
    • ↳ id string optional
      The provider-assigned resource ID.
    • ↳ matches map[string]array optional
      Matched search terms mapped to their highlighted values.
    • ↳ modified string optional
      The ISO 8601 timestamp when the resource was last updated in the index.
    • ↳ module string required
      The module that contains this resource.
    • ↳ name string optional
      The name of the resource.
    • ↳ package string required
      The package that provides this resource.
    • ↳ parent_urn string optional
      The URN of the parent resource, if any.
    • ↳ pending string optional
      The pending operation on this resource, if any (e.g. creating, updating, deleting).
    • ↳ project string optional
      The project that contains this resource.
    • ↳ protected boolean optional
      Whether this resource is protected from deletion.
    • ↳ provider_urn string optional
      The URN of the provider for this resource.
    • ↳ stack string optional
      The stack that contains this resource.
    • ↳ type string optional
      The full type token of the resource (e.g. aws:s3/bucket:Bucket).
    • ↳ urn string optional
      The URN uniquely identifying this resource within a stack.
    • ↳ teams array[string] optional
      The teams that have access to this resource.
    • ↳ properties object optional
      The resource’s input/output properties as a JSON object. Only populated when explicitly requested.
    • ↳ metadata object optional
      Additional metadata associated with the resource.
    • ↳ category string optional
      The category of the resource.
    • ↳ account string optional
      The Insights account name that discovered or manages this resource.
    • ↳ dependents array[string] optional
      URNs of resources that depend on this resource.
    • ↳ managed string optional
      What manages this resource’s lifecycle: ‘Pulumi’ for a resource in a Pulumi IaC stack, ‘Terraform’ / ‘CloudFormation’ / ‘ARM’ for one discovered under another IaC tool, and ‘Other’ for one Insights scanning found under no known tool.
    • ↳ fingerprint string optional
      A fingerprint uniquely identifying this resource’s state.
    • ↳ sourceCount integer optional
      The number of sources for this resource.
    • aggregations map[string]Aggregation optional
      Aggregation buckets for faceted search.
    • pagination ResourceSearchPagination optional
      Pagination links for navigating through results.
    • ↳ previous string optional
      Link to the previous page of results.
    • ↳ next string optional
      Link to the next page of results.
    • ↳ cursor string optional
      An opaque cursor for resuming pagination.
    Errors: 404 Organization not found 422 search cluster is unreachable

    Get Natural Language Query

    ▼
    GET /api/orgs/{orgName}/search/resources/parse

    GetNaturalLanguageQuery converts a natural language query into a structured Pulumi search query using AI. For example, converts ‘show me all S3 buckets in production’ into a proper search syntax.

    Request Parameters

    • orgName string path required
      The organization name
    • query string query optional
      Search query string

    Responses

    200 OK
    Schema: GetNaturalLanguageQueryResponse
    • query string required
      The translated query string
    Errors: 400 please provide a query 402 AI assist feature requires Enterprise subscription 404 NLP search feature not enabled 503 AI services are temporarily unavailable

    Get Org Resource Search V2Query

    ▼
    GET /api/orgs/{orgName}/search/resourcesv2

    Searches for resources within an organization with advanced filtering, sorting, and pagination capabilities.

    Pagination: The page parameter supports up to 10,000 results. For larger result sets, use the cursor parameter instead (Enterprise plans only). Note that pagination is not transactional — result ordering may change if a stack update completes during pagination.

    Sorting: The sort parameter accepts: created, custom, delete, dependencies, id, modified, module, name, package, parentUrn, project, protected, providerUrn, stack, type, urn, managed, category. If omitted, results are sorted by search relevance (or last modified time when no query is provided).

    Properties: Set properties=true to include resource input/output values.

    Collapse: Set collapse=true to consolidate resources that exist in multiple sources (e.g., both IaC stacks and Insights scans) into a single result.

    Request Parameters

    • orgName string path required
      The organization name
    • asc boolean query optional
      Sort in ascending order when true, descending when false
    • collapse boolean query optional
      Collapse results to show one entry per stack instead of per resource
    • cursor string query optional
      Cursor for paginated results
    • facet array query optional
      Facet filters to apply
    • groupBy string query optional
      Group results by this field
    • page integer query optional
      Page number for pagination
    • properties boolean query optional
      Include resource properties in search results (may increase response size)
    • query string query optional
      Search query string
    • size integer query optional
      Number of results to return
    • sort array query optional
      Sort order for results
    • top integer query optional
      Number of top aggregation buckets to return

    Responses

    200 OK
    Schema: ResourceSearchResult
    • total integer optional
      The total number of matching resources.
    • resources array[ResourceResult] optional
      The list of matching resource results.
    • ↳ created string optional
      The ISO 8601 timestamp when the resource was first indexed.
    • ↳ custom boolean optional
      Whether this is a custom resource managed by a provider plugin.
    • ↳ delete boolean optional
      Whether this resource is pending deletion.
    • ↳ dependencies array[string] optional
      URNs of resources that this resource depends on.
    • ↳ external boolean optional
      Whether the lifecycle of this resource is not managed by Pulumi.
    • ↳ id string optional
      The provider-assigned resource ID.
    • ↳ matches map[string]array optional
      Matched search terms mapped to their highlighted values.
    • ↳ modified string optional
      The ISO 8601 timestamp when the resource was last updated in the index.
    • ↳ module string required
      The module that contains this resource.
    • ↳ name string optional
      The name of the resource.
    • ↳ package string required
      The package that provides this resource.
    • ↳ parent_urn string optional
      The URN of the parent resource, if any.
    • ↳ pending string optional
      The pending operation on this resource, if any (e.g. creating, updating, deleting).
    • ↳ project string optional
      The project that contains this resource.
    • ↳ protected boolean optional
      Whether this resource is protected from deletion.
    • ↳ provider_urn string optional
      The URN of the provider for this resource.
    • ↳ stack string optional
      The stack that contains this resource.
    • ↳ type string optional
      The full type token of the resource (e.g. aws:s3/bucket:Bucket).
    • ↳ urn string optional
      The URN uniquely identifying this resource within a stack.
    • ↳ teams array[string] optional
      The teams that have access to this resource.
    • ↳ properties object optional
      The resource’s input/output properties as a JSON object. Only populated when explicitly requested.
    • ↳ metadata object optional
      Additional metadata associated with the resource.
    • ↳ category string optional
      The category of the resource.
    • ↳ account string optional
      The Insights account name that discovered or manages this resource.
    • ↳ dependents array[string] optional
      URNs of resources that depend on this resource.
    • ↳ managed string optional
      What manages this resource’s lifecycle: ‘Pulumi’ for a resource in a Pulumi IaC stack, ‘Terraform’ / ‘CloudFormation’ / ‘ARM’ for one discovered under another IaC tool, and ‘Other’ for one Insights scanning found under no known tool.
    • ↳ fingerprint string optional
      A fingerprint uniquely identifying this resource’s state.
    • ↳ sourceCount integer optional
      The number of sources for this resource.
    • aggregations map[string]Aggregation optional
      Aggregation buckets for faceted search.
    • pagination ResourceSearchPagination optional
      Pagination links for navigating through results.
    • ↳ previous string optional
      Link to the previous page of results.
    • ↳ next string optional
      Link to the next page of results.
    • ↳ cursor string optional
      An opaque cursor for resuming pagination.
    Errors: 400 invalid groupBy field 422 search cluster is unreachable

      The infrastructure as code platform for any cloud.

      Contact us Get started