---
title: "Initiate a query with a callback to receive the response"
method: POST
path: "/asyncquery"
tags: ["asyncquery"]
---

# Initiate a query with a callback to receive the response

`POST /asyncquery`

## Request body

- AsyncQuery — The AsyncQuery class is effectively the same as the Query class but it requires a callback property.
  - `callback` string, uri, required — Upon completion, this server will send a POST request to the callback URL with `Content-Type: application/json` header and request body containing a JSON-encoded `Response` object. The server MAY POST `Response` objects before work is fully complete to provide interim results with a Response.status value of 'Running'. If a POST operation to the callback URL does not succeed, the server SHOULD retry the POST at least once.
  - `message` Message, required — The message object holds the main content of a Query or a Response in three properties: query_graph, results, and knowledge_graph. The query_graph property contains the query configuration, the results property contains any answers that are returned by the service, and knowledge_graph property contains lists of edges and nodes in the thought graph corresponding to this message. The content of these properties is context-dependent to the encompassing object and the TRAPI operation requested.
    - `results` Result[], nullable — List of all returned Result objects for the query posed. The list SHOULD NOT be assumed to be ordered. The 'score' property, if present, MAY be used to infer result rankings. If Results are not expected (such as for a query Message), this property SHOULD be null or absent. If Results are expected (such as for a response Message) and no Results are available, this property SHOULD be an array with 0 Results in it.
      - `node_bindings` object, required — The dictionary of Input Query Graph to Result Knowledge Graph node bindings where the dictionary keys are the key identifiers of the Query Graph nodes and the associated values of those keys are instances of NodeBinding schema type (see below). This value is an array of NodeBindings since a given query node may have multiple knowledge graph Node bindings in the result.
      - `analyses` Analysis[], required — The list of all Analysis components that contribute to the result. See below for Analysis components.
        - `resource_id` string, required — A Compact URI, consisting of a prefix and a reference separated by a colon, such as UniProtKB:P00738. Via an external context definition, the CURIE prefix and colon may be replaced by a URI prefix, such as http://identifiers.org/uniprot/, to form a full URI.
        - `score` number, float, nullable — A numerical score associated with this result indicating the relevance or confidence of this result relative to others in the returned set. Higher MUST be better.
        - `edge_bindings` object, required — The dictionary of input Query Graph to Knowledge Graph edge bindings where the dictionary keys are the key identifiers of the Query Graph edges and the associated values of those keys are instances of EdgeBinding schema type (see below). This value is an array of EdgeBindings since a given query edge may resolve to multiple Knowledge Graph Edges.
        - `support_graphs` string[], nullable — This is a list of references to Auxiliary Graph instances that supported the analysis of a Result as performed by the reasoning service. Each item in the list is the key of a single Auxiliary Graph.
        - `scoring_method` string, nullable — An identifier and link to an explanation for the method used to generate the score
        - `attributes` Attribute[], nullable — The attributes of this particular Analysis.
          - `attribute_type_id` string, required — A Compact URI, consisting of a prefix and a reference separated by a colon, such as UniProtKB:P00738. Via an external context definition, the CURIE prefix and colon may be replaced by a URI prefix, such as http://identifiers.org/uniprot/, to form a full URI.
          - `original_attribute_name` string, nullable — The term used by the original source of an attribute to describe the meaning or significance of the value it captures. This may be a column name in a source tsv file, or a key in a source json document for the field in the data that held the attribute's value. Capturing this information where possible lets us preserve what the original source said. Note that the data type is string' but the contents of the field could also be a CURIE of a third party ontology term.
          - `value` unknown, required
          - `value_type_id` string — A Compact URI, consisting of a prefix and a reference separated by a colon, such as UniProtKB:P00738. Via an external context definition, the CURIE prefix and colon may be replaced by a URI prefix, such as http://identifiers.org/uniprot/, to form a full URI.
          - `attribute_source` string, nullable — The source of the core assertion made by the key-value pair of an attribute object. Use a CURIE or namespace designator for this resource where possible.
          - `value_url` string, nullable — Human-consumable URL linking to a web document that provides additional information about an attribute's value (not the node or the edge fom which it hangs).
          - `description` string, nullable — Human-readable description for the attribute and its value.
          - `attributes` Attribute[], nullable — A list of attributes providing further information about the parent attribute (for example to provide provenance information about the parent attribute).
      - `id` string, nullable — URI for this result
      - `description` string, nullable — A free text description of this result answer from the reasoner
      - `essence` string, nullable — A single string that is the terse essence of the result (useful for simple answers)
      - `essence_category` string, nullable — A Translator BioLink bioentity category of the essence
      - `row_data` union[], nullable — An arbitrary list of values that captures the essence of the result that can be turned into a tabular result across all answers (each result is a row) for a user that wants simplified tabular output
        - union
          - string
          - number
      - `score` number, float, nullable — A numerical score associated with this result indicating the relevance or confidence of this result relative to others in the returned set. Higher MUST be better.
      - `score_name` string, nullable — Name for the score
      - `score_direction` string, nullable — Sorting indicator for the score: one of higher_is_better or lower_is_better
      - `confidence` number, float, nullable — Confidence metric for this result, a value between (inclusive) 0.0 (no confidence) and 1.0 (highest confidence)
      - `result_group` integer, nullable — An integer group number for results for use in cases where several results should be grouped together. Also useful to control sorting ascending.
      - `result_group_similarity_score` number, float, nullable — A score that denotes the similarity of this result to other members of the result_group
      - `resource_id` string, nullable — Identifier string of the resource that provided this result (one of ARAX, Aragorn, etc.)
    - `query_graph` QueryGraph — A graph representing a biomedical question. It serves as a template for each result (answer), where each bound knowledge graph node/edge is expected to obey the constraints of the associated query graph element.
      - `nodes` object, required — The node specifications. The keys of this map are unique node identifiers and the corresponding values include the constraints on bound nodes.
      - `edges` object, required — The edge specifications. The keys of this map are unique edge identifiers and the corresponding values include the constraints on bound edges, in addition to specifying the subject and object QNodes.
    - `knowledge_graph` KnowledgeGraph — The knowledge graph associated with a set of results. The instances of Node and Edge defining this graph represent instances of biolink:NamedThing (concept nodes) and biolink:Association (relationship edges) representing (Attribute) annotated knowledge returned from the knowledge sources and inference agents wrapped by the given TRAPI implementation.
      - `nodes` object, required — Dictionary of Node instances used in the KnowledgeGraph, referenced elsewhere in the TRAPI output by the dictionary key.
      - `edges` object, required — Dictionary of Edge instances used in the KnowledgeGraph, referenced elsewhere in the TRAPI output by the dictionary key.
    - `auxiliary_graphs` object — Dictionary of AuxiliaryGraph instances that are used by Knowledge Graph Edges and Result Analyses. These are referenced elsewhere by the dictionary key.
  - `log_level` 'ERROR' | 'WARNING' | 'INFO' | 'DEBUG' — Logging level
  - `workflow` OperationLookup[] — List of workflow steps to be executed.
    - `id` 'lookup', required
    - `parameters` unknown
  - `submitter` string, nullable — Any string for self-identifying the submitter of a query. The purpose of this optional field is to aid in the tracking of the source of queries for development and issue resolution.
  - `bypass_cache` boolean — Set to true in order to request that the agent obtain fresh information from its sources in all cases where it has a viable choice between requesting fresh information in real time and using cached information. The agent receiving this flag MUST also include it in TRAPI sent to downstream sources (e.g., ARS -> ARAs -> KPs).

## Response `200`

The query is accepted for processing and the Response will be sent to the callback url when complete.

- AsyncQueryResponse — The AsyncQueryResponse object contains a payload that must be returned from a submitted async_query.
  - `status` string, nullable — One of a standardized set of short codes: e.g. Accepted, QueryNotTraversable, KPsNotAvailable
  - `description` string, nullable — A brief human-readable description of the result of the async_query submission.
  - `job_id` string, required — An identifier for the submitted job that can be used with /async_query_status to receive an update on the status of the job.

## Other responses

- `400` — Bad request. The request is invalid according to this OpenAPI schema OR a specific identifier is believed to be invalid somehow (not just unrecognized).
- `413` — Payload too large. Indicates that batch size was over the limit specified in x-trapi.
- `429` — Too many requests. Indicates that the client issued requests that exceed the rate limit specified in x-trapi.
- `500` — Internal server error.
- `501` — Not implemented.

---

[API](https://skmtc.net/rtxteam/apis/rtx-kg2-trapi-1-5-0.md) · [All operations](https://skmtc.net/rtxteam/apis/rtx-kg2-trapi-1-5-0/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/rtxteam/rtx-kg2-trapi-1-5-0/versions/e65b311ece6d/schema)