Submitting a Query

VQL queries go to the /query REST interface.

POST/api/{version}/query

Headers

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.
`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.

Body Parameters

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`.

Request

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/v19.3/query

Response

{
   "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"
       }
   ]
}

Response Details

On SUCCESS, the response includes the following information:

Name	Description
`pagesize`	The number of records displayed per page. This can be modified. Learn more.
`pageoffset`	The records displayed on the current page are offset by this number of records. Learn more.
`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.
`next_page`	The Pagination URL to navigate to the next page of results. This is not always available. Learn more.
`data`	All records found.

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:

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

The field metadata may include some or all of the following:

Metadata Field	Description
`name`	Name of the field.
`label`	The UI label of the field.
`type`	The data type, for example, `string` or `int`
`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 the field is required.
`unique`	Indicates if the value must be unique (true/false).
`status`	Indicates if the field is active (active/inactive).
`picklist`	The picklist name field value.
`encrypted`	If `true`, the Contains Protected Health Information (PHI) or Personally Identifiable Information (PHI) setting is selected for this field. Learn more in Vault Help.

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:

Name	Description
`id`	The record ID.
`field_properties`	Includes arrays of `hidden` and `redacted` fields. To return only hidden or redacted fields, set the `X-VaultAPI-RecordProperties` header to `hidden` or `redacted`, respectively.
`field_additional_data`	Includes configuration data for `link` type formula fields. To return only this data, set the `X-VaultAPI-RecordProperties` header to `weblink`.

For each field, the field_additional_data metadata includes the name of the field and the web_link object, which contains the following metadata:

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.