# Create async query from query spec

Submit an assessment query specification for asynchronous execution, returning node-level results.

This is the spec-based (non-saved-query) variant of async node queries. For executing a saved query, see [Create async query nodes](/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/createassessmentquerynodesasync.md).

{% openapi src="/files/Aco9gj4MY2XoNiD4zIjr" path="/api/v1/assessments/query\_spec:nodes\_async\_create" method="post" %}
[openapi.yaml](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-f5344805587160cf141bde637e04e03e2aa86778%2Fopenapi.yaml?alt=media)
{% endopenapi %}

### Request types (mutually exclusive)

Set exactly one of these fields in the request body. Each field wraps a `request` object, which in turn wraps the query specification in a `body` field (`GetAssessmentQuerySpecResultRequest`):

| Field                        | Behavior                                                                                               |
| ---------------------------- | ------------------------------------------------------------------------------------------------------ |
| `cached_result_if_available` | Return cached results within `max_staleness` (default 24h); execute a new query if no valid cache hit. |
| `immediate_run`              | Always run a new query, ignoring cached results. The new result is added to the cache.                 |
| `cached_result_context`      | Connect to a specific cached result by `cache_id`. Fails if the entry does not exist or has expired.   |

Each option wraps the query specification in a nested `request.body` field. Examples for all three variants:

**`cached_result_if_available`** — return a cached result within `max_staleness`, or run a new query if no valid cache exists:

```json
{
  "cached_result_if_available": {
    "request": {
      "body": {
        "query_type": "SOURCE_TO_DESTINATION",
        "source_node_types": { "nodes": [{ "node_type": "OktaUser" }] },
        "node_relationship_type": "EFFECTIVE_ACCESS",
        "result_value_type": "SOURCE_NODES_WITH_COUNTS"
      }
    },
    "max_staleness": "86400s"
  }
}
```

**`immediate_run`** — always execute a new query, ignoring any cached results:

```json
{
  "immediate_run": {
    "request": {
      "body": {
        "query_type": "SOURCE_TO_DESTINATION",
        "source_node_types": { "nodes": [{ "node_type": "OktaUser" }] },
        "node_relationship_type": "EFFECTIVE_ACCESS",
        "result_value_type": "SOURCE_NODES_WITH_COUNTS"
      }
    }
  }
}
```

**`cached_result_context`** — connect directly to a known cached result by its `cache_id`. Fails if the cache entry does not exist or has expired:

```json
{
  "cached_result_context": {
    "cache_id": "<cache-id-from-previous-response>"
  }
}
```

The top-level `request` field is deprecated. Use one of the above fields instead.

### Response

The response includes:

| Field                     | Description                                                                                                                   |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `query_result_id`         | Task ID to poll using [GetQuerySpecNodesAsync](/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/getqueryspecnodesasync.md). |
| `cache_id`                | Cache identifier for this execution (use in future `cached_result_context` requests).                                         |
| `last_completed_cache_id` | The most recent completed cache entry for this query spec. Present if a cached result is already available.                   |

### Workflow

1. Submit the query using this endpoint.
2. The response includes a `query_result_id`.
3. If `last_completed_cache_id` is present, results may be available immediately.
4. Poll results using [GetQuerySpecNodesAsync](/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/getqueryspecnodesasync.md) until `status` = `DONE`.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/createqueryspecnodesasync.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.