Version 2.0

Execute Query

POST/api/v2/functions/queries/{queryApiName}/execute

Warning

This endpoint is in preview and may be modified or removed at any time. To use this endpoint, add preview=true to the request query parameters.

Executes a Query and returns the result as a single JSON object. By default, this executes the latest version of the query. The latest version is the one that was most recently published, which may be a pre-release version.

This endpoint executes global (non-ontology-scoped) query functions. For ontology-scoped functions, use the equivalent endpoint under /v2/ontologies/{ontology}/queries/{queryApiName}/execute. For streaming or incremental result delivery, use streamingExecute.

Third-party applications using this endpoint via OAuth2 must request the following operation scope: api:functions-execute.

Path parameters

queryApiName

string

The name of the Query in the API.

Query parameters

transactionId

stringoptional

The ID of a transaction to read from. Transactions are an experimental feature and not all workflows may be supported.

preview

booleanoptional

Enables the use of preview functionality.

Request body

ExecuteQueryRequest

object

Hide child attributes

parameters

map<ParameterId, DataValue>optional

Show child attributes

version

stringoptional

The version of the query to execute. When used with branch, the specified version must exist on the branch.

branch

stringoptional

The Foundry branch to execute the query from. If not specified, the default branch is used. When provided without version, the latest version on this branch is used. When provided with version, the specified version must exist on the branch.

Response body

ExecuteQueryResponse

object

Hide child attributes

value

any

Represents the value of data in the following format. Note that these values can be nested, for example an array of structs.

Type	JSON encoding	Example
Array	array	`["alpha", "bravo", "charlie"]`
Attachment	string	`"ri.attachments.main.attachment.2f944bae-5851-4204-8615-920c969a9f2e"`
Boolean	boolean	`true`
Byte	number	`31`
Date	ISO 8601 extended local date string	`"2021-05-01"`
Decimal	string	`"2.718281828"`
Float	number	`3.14159265`
Double	number	`3.14159265`
Integer	number	`238940`
Long	string	`"58319870951433"`
Marking	string	`"MU"`
Null	null	`null`
Set	array	`["alpha", "bravo", "charlie"]`
Short	number	`8739`
String	string	`"Call me Ishmael"`
Struct	JSON object	`{"name": "John Doe", "age": 42}`
TwoDimensionalAggregation	JSON object	`{"groups": [{"key": "alpha", "value": 100}, {"key": "beta", "value": 101}]}`
ThreeDimensionalAggregation	JSON object	`{"groups": [{"key": "NYC", "groups": [{"key": "Engineer", "value" : 100}]}]}`
Timestamp	ISO 8601 extended offset date-time string in UTC zone	`"2021-01-04T05:00:00Z"`

Examples

Request

Copied!

curl -X POST \
\t-H "Content-type: application/json" \
\t-H "Authorization: Bearer $TOKEN" \
	"https://$HOSTNAME/api/v2/functions/queries/myQueryFunction/execute?transactionId=transaction-1&preview=true" \
	-d '{"parameters":{"price":29.99},"version":"1.2.3","branch":"ri.branch..branch.d827184f-ee0e-4351-8b70-efbe51e07252"}'

Response

Copied!

{
  "value": 29.99
}

Error responses

Error Name
`ExecuteQueryPermissionDenied`	Error Code	`PERMISSION_DENIED`
	Status Code	403
	Description	Could not execute the Query.
	Parameters	`queryApiName`

See Errors for a general overview of errors in the platform.