**Source URL:** https://limited.veevavault.dev/vault-api/api-reference/24.2/vault-query-language-vql/submitting-a-query.md

# Submitting a Query



VQL queries go to the `/query` interface.

<Endpoint path="/api/{version}/query" method="POST"></Endpoint>

## Headers {#headers}

<FieldTable>
| Name | Description |
| --- | --- |
| `Accept` | `application/json` (default) or `application/xml` |
| Content-Type | `application/x-www-form-urlencoded` or `multipart/form-data` |
| `X-VaultAPI-DescribeQuery` | Set to `true` to include static field metadata in the response for the data record. If not specified, the response does not include any static field metadata. This option eliminates the need to make additional API calls to understand the shape of query response data. [Learn More](/vault-api/api-reference/24.2/metadata-definition-language-mdl). |
| `X-VaultAPI-RecordProperties` | Optional: If present, the response includes the record properties object. Possible values are `all`, `hidden`, `redacted`, and `weblink`. If omitted, the record properties object is not included in the response. [Learn more](/vault-api/api-reference/24.2/metadata-definition-language-mdl). |
</FieldTable>

## Body Parameters {#body-parameters}

<FieldTable>
| Name | Description |
| --- | --- |
| `q` | Place your query of up to 50,000 characters in the body of your request. Note that, while the API also allows you to submit your query as a query parameter, doing so may cause you to exceed the maximum URL length. Queries should be formatted as `q={query}`. For example, `q=SELECT id FROM documents`. |
</FieldTable>

## Request {#request}

<CodeExample title="">
```
curl -X POST -H "Authorization: {SESSION_ID}" \
-H "X-VaultAPI-DescribeQuery: true" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Accept: application/json" \
--data-urlencode "q=SELECT id, name__v FROM documents WHERE product__v = ‘cholecap’"
https://myvault.veevavault.com/api/v21.1/query

```
</CodeExample>

## Response {#response}

<CodeExample title="">
```
{
   "responseStatus": "SUCCESS",
   "queryDescribe": {
       "object": {
           "name": "documents",
           "label": "documents",
           "label_plural": "documents"
       },
       "fields": [
           {
               "type": "id",
               "required": true,
               "name": "id"
           },
           {
               "label": "Name",
               "type": "String",
               "required": true,
               "name": "name__v",
               "max_length": 100
           }
       ]
   },
   "responseDetails": {
       "pagesize": 1000,
       "pageoffset": 0,
       "size": 5,
       "total": 5
   },
   "data": [
       {
           "id": 72,
           "name__v": "Cholecap-2021-brochure"
       },
       {
           "id": 63,
           "name__v": "Cholecap - Multisequence"
       },
       {
           "id": 36,
           "name__v": "Cholecap Study"
       },
       {
           "id": 25,
           "name__v": "Clinical Trial Reference"
       },
       {
           "id": 24,
           "name__v": "Formulary Guidelines"
       }
   ]
}

```
</CodeExample>

## Response Details {#response-details}

On `SUCCESS`, the response includes the following information:

<FieldTable>
| Name | Description |
| --- | --- |
| `pagesize` | The number of records displayed per page. This can be modified. [Learn more](/vql/clauses/pagesize). |
| `pageoffset` | The records displayed on the current page are offset by this number of records. [Learn more](/vql/references/query-performance-best-practices#Paginating_Results). |
| `size` | The total number of records displayed on the current page. |
| `total` | The total number of records found. |
| `previous_page` | The Pagination URL to navigate to the previous page of results. This is not always available. [Learn more](/vql/references/query-performance-best-practices#Paginating_Results). |
| `next_page` | The Pagination URL to navigate to the next page of results. This is not always available. [Learn more](/vql/references/query-performance-best-practices#Paginating_Results). |
| `data` | All records found. |
</FieldTable>

## About the X-VaultAPI-DescribeQuery Header {#about-the-x-vaultapi-describequery-header}

When you include the `X-VaultAPI-DescribeQuery` header and set it to `true`, the query response includes the following static metadata description:

<FieldTable>
| Name | Description |
| --- | --- |
| `name` | The name of the queryable object. |
| `label` | The label of the queryable object. |
| `label_plural` | The plural label of the queryable object |
</FieldTable>
The field metadata may include some or all of the following:

<FieldTable>
| Metadata Field | Description |
| --- | --- |
| `name` | The name of the field. |
| `label` | The UI label of the field. |
| `type` | The data type, for example, `String` or `Number` |
| `max_length` | The max length of a string field. |
| `max_value` | The max value of a number field. |
| `min_value` | The minimum value of a number field. |
| `scale` | The number of digits after a decimal point in a number field. |
| `required` | Indicates whether the field is required (`true`/`false`). |
| `unique` | Indicates whether the value must be unique (`true`/`false`). |
| `status` | Indicates whether the field is active (`active`/`inactive`). |
| `picklist` | The picklist name field value. |
| `encrypted` | Indicates whether the *Contains Protected Health Information (PHI) or Personally Identifiable Information (PHI)* setting is selected for this field (`true`/`false`). Learn more in [Vault Help](https://platform.veevavault.help/en/lr/15057). |
| `format_mask` | The format mask expression if it exists. Learn more about format masks in [Vault Help](https://platform.veevavault.help/en/lr/15057). |
| `function` | The function name if the VQL query applies a [function](/vql/functions-options) to this field. |
| `alias` | If `true`, the VQL query applies an [alias](/vql/clauses/as) to this field. Omitted if `false`. |
</FieldTable>
**Note:** For formula fields, `queryDescribe` should describe the field as specified in the metadata, excluding the `formula` attribute.

## About the X-VaultAPI-RecordProperties Header {#about-the-x-vaultapi-recordproperties-header}

When you include the `X-VaultAPI-RecordProperties` header, the query response includes the `record_properties` object. The `record_properties` object describes the properties of a data record. If set to `all`, for each record, the response includes:

<FieldTable>
| Name | Description |
| --- | --- |
| `id` | The record ID. |
| `field_properties` | Includes arrays of `hidden`, editable (`edit`), and `redacted` fields. To return only hidden or redacted fields, set the `X-VaultAPI-RecordProperties` header to `hidden` or `redacted`, respectively. |
| `permissions` | Includes whether this record has `read`, `edit`, `create`, and `delete` permissions. |
| `subquery_properties` | Includes an array of hidden subquery relationships for this record. |
| `field_additional_data` | Includes configuration data for `link` type formula fields. To return only this data, set the `X-VaultAPI-RecordProperties` header to `weblink`. |
</FieldTable>
For each field, the `field_additional_data` metadata includes the name of the field and the `web_link` object, which contains the following metadata:

<FieldTable>
| Metadata Field | Description |
| --- | --- |
| `label` | The text that appears as a link in the Vault UI. |
| `target` | Determines whether the link will open in a `new_window` or the `same_window`. |
| `connection` | Populates another Vault's DNS within the URL utilizing a configured `connection__sys` object record. |
</FieldTable>

## About the X-VaultAPI-Facets Header {#about-the-x-vaultapi-facets-header}

When you include the `X-VaultAPI-Facets` header with a list of facetable fields, the response includes the `facets` object containing the count of unique values for each facetable field. Determine which fields are facetable using the [Retrieve Object Metadata API](/vault-api/api-reference/24.2/vault-objects/retrieve-object-metadata). For each facetable field included in the header, the response includes:

<FieldTable>
| Name | Description |
| --- | --- |
| `label` | The label for the facetable field in the Vault UI. |
| `type` | The field’s data type. |
| `name` | The name of the facetable field. |
| `count` | The number of unique values for this field in the Vault. |
| `truncated_list` | A boolean indicating that the list is truncated because it contains more than 50 values. |
</FieldTable>
The `values` metadata contains the unique values for the facetable field in the Vault, sorted first by `result_count` and secondly by `value`.



---

**Previous:** [Vault Query Language (VQL)](/vault-api/api-reference/24.2/vault-query-language-vql)  
**Next:** [Metadata Definition Language (MDL)](/vault-api/api-reference/24.2/metadata-definition-language-mdl)