Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Query Service Query Templates API
description: "Use the Adobe Experience Platform Query Service API to query Platform data with standard SQL. With this serverless tool, you can join any datasets in the [Experience Platform Data Lake](https://experienceleague.adobe.com/docs/experience-platform/landing/license/data-management-best-practices.html#understanding-adobe-experience-platform-data-storage) and capture the query results as a new dataset for use in reporting, Data Science Workspace, or for ingestion into Real-time Customer Profile.\n\n**Related Documentation**:\n * [Query Service documentation](http://www.adobe.com/go/query-service-home-en)\n\n**Visualize API calls with Postman (a free, third-party software)**:\n * [Query Service API Postman collection on GitHub](https://github.com/adobe/experience-platform-postman-samples/blob/master/apis/experience-platform/Query%20Service%20API.postman_collection.json)\n * [Video guide for creating the Postman environment](https://video.tv.adobe.com/v/28832)\n * [Steps for importing environments and collections in Postman](https://learning.getpostman.com/docs/postman/collection_runs/using_environments_in_collection_runs/)\n\n**API paths**:\n * PLATFORM Gateway URL: https://<span>platform.adobe.io/\n * Base path for this API: /data/foundation/query\n * Example of a complete path: https://<span>platform.adobe.io/data/foundation/query/queries\n\n**Required headers**:\n * All calls require the headers `Authorization`, `x-gw-ims-org-id`, and `x-api-key`. For more information on how to obtain these values, see the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).\n * All resources in Experience Platform are isolated to specific virtual sandboxes. All requests to Platform APIs require the header `x-sandbox-name` whose value is the all-lowercase name of the sandbox the operation will take place in (for example, \"prod\"). See the [sandboxes overview](https://adobe.com/go/sandbox-overview-en) for more information.\n * All requests with a payload in the request body (such as POST, PUT, and PATCH calls) must include the header `Content-Type` with a value of `application/json`.\n\n**API error handling**:\n * Refer to the Experience Platform API troubleshooting guide for [FAQs](https://experienceleague.adobe.com/docs/experience-platform/landing/troubleshooting.html?lang=en#faq), [API status codes](https://experienceleague.adobe.com/docs/experience-platform/landing/troubleshooting.html?lang=en#api-status-codes), and [request header errors](https://experienceleague.adobe.com/docs/experience-platform/landing/troubleshooting.html?lang=en#request-header-errors).\n * Refer to the Query Service troubleshooting guide for [common query related FAQs](https://experienceleague.adobe.com/docs/experience-platform/query/troubleshooting-guide.html)."
version: '1.0'
servers:
- url: //{environment}.adobe.io/data/foundation/query
variables:
environment:
default: platform
enum:
- platform
- platform-stage
tags:
- name: Query Templates
description: Query templates let you create, store, and execute any query as an ad hoc or scheduled service.
paths:
/query-templates:
get:
tags:
- Query Templates
summary: List query templates
operationId: listQueryTemplates
description: This request provides a list of every query template.
parameters:
- name: Authorization
in: header
description: The access token which can be copied from your Experience Platform integration, prefixed with "Bearer " (for example, `Bearer {ACCESS_TOKEN}`). For more information on how to obtain this value, visit the documentation covering making API calls in the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
required: true
schema:
type: string
- name: x-gw-ims-org-id
in: header
description: The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the documentation covering making API calls in the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
required: true
schema:
type: string
- name: x-api-key
in: header
description: The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the documentation covering making API calls in the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
required: true
schema:
type: string
- name: x-sandbox-name
in: header
description: The name of the sandbox in which the operation will take place. See the [sandboxes overview documentation](https://adobe.com/go/sandbox-overview-en) for more information.
required: true
schema:
type: string
- name: x-request-id
in: header
description: An optional header that serves as a tracking ID for the request. If one is not provided on the request, the server generates one automatically.
schema:
type: string
- name: User-Agent
in: header
description: The type of the client making the HTTP request.
schema:
type: string
- name: isPrevLink
in: query
description: '`isPrevLink` is part of pagination. Results are sorted using the `created` timestamp and the `orderby` property. When navigating pages of results, `isPrevLink` is set to true when paging backwards. It reverses the order of the query. See "next" and "prev" links as examples.'
schema:
type: boolean
- name: orderby
in: query
description: The field that specifies the order of results. The supported fields are `created` and `updated`. Prepend the property name with `+` for ascending and `-` for descending order. The default is `-created`. Note that the plus sign (`+`) has to be escaped with `%2B`. For example `%2Bcreated` is the value for an ascending created order.
schema:
type: string
- name: limit
in: query
description: Restrict the maximum number of records that should be returned for a given request.
schema:
type: integer
- name: start
in: query
description: The timestamp used with `orderby` to order the returned results.
schema:
type: string
- name: property
in: query
description: "Comma-separated filters. Multiple filters separated by commas can be passed.\n\n List of properties that allow filtering: `name`, `userId`, `lastUpdatedBy`.\n\n * The `name` property can only be filtered with the `~` (contains) operator.\n Only one name string WITHOUT a comma can be included. For example, `property=name~maria`.\n\n * The `userId` and the `lastUpdatedBy` properties can be used with the `==` (equal to) operator.\n Only one name string WITHOUT a comma can be included. For example, `property=userId==49D005796000B4B20A495J85@acme.adobe.com`"
schema:
type: string
responses:
200:
x-summary: Success
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/query_template_list'
401:
x-summary: Unauthorized
description: Unauthorized
content: {}
404:
x-summary: Not found
description: Not Found
content: {}
'500':
x-summary: Internal server error
description: There was an internal server error. Try the request again in a few minutes, and contact Adobe Support if the problem persists.
content: {}
post:
tags:
- Query Templates
summary: Create a query template
operationId: createQueryTemplate
description: This request creates a query template.
parameters:
- name: Authorization
in: header
description: The access token which can be copied from your Experience Platform integration, prefixed with "Bearer " (for example, `Bearer {ACCESS_TOKEN}`). For more information on how to obtain this value, visit the documentation covering making API calls in the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
required: true
schema:
type: string
- name: x-gw-ims-org-id
in: header
description: The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the documentation covering making API calls in the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
required: true
schema:
type: string
- name: x-api-key
in: header
description: The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the documentation covering making API calls in the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
required: true
schema:
type: string
- name: x-sandbox-name
in: header
description: The name of the sandbox in which the operation will take place. See the [sandboxes overview documentation](https://adobe.com/go/sandbox-overview-en) for more information.
required: true
schema:
type: string
- name: x-request-id
in: header
description: An optional header that serves as a tracking ID for the request. If one is not provided on the request, the server generates one automatically.
schema:
type: string
- name: User-Agent
in: header
description: The type of the client making the HTTP request.
schema:
type: string
requestBody:
description: The query template to be created.
content:
application/json:
schema:
$ref: '#/components/schemas/query_template_def'
required: true
responses:
202:
x-summary: Success
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/query_template'
401:
x-summary: Unauthorized
description: Unauthorized
content: {}
'500':
x-summary: Internal server error
description: There was an internal server error. Try the request again in a few minutes, and contact Adobe Support if the problem persists.
content: {}
x-codegen-request-body-name: queryTemplate
/query-templates/count:
get:
tags:
- Query Templates
summary: Retrieve the count of query templates
operationId: retrieveQueryTemplateCount
description: This request retrieves the count of query templates.
parameters:
- name: Authorization
in: header
description: The access token which can be copied from your Experience Platform integration, prefixed with "Bearer " (for example, `Bearer {ACCESS_TOKEN}`). For more information on how to obtain this value, visit the documentation covering making API calls in the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
required: true
schema:
type: string
- name: x-gw-ims-org-id
in: header
description: The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the documentation covering making API calls in the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
required: true
schema:
type: string
- name: x-api-key
in: header
description: The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the documentation covering making API calls in the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
required: true
schema:
type: string
- name: x-sandbox-name
in: header
description: The name of the sandbox in which the operation will take place. See the [sandboxes overview documentation](https://adobe.com/go/sandbox-overview-en) for more information.
required: true
schema:
type: string
- name: x-request-id
in: header
description: An optional header that serves as a tracking ID for the request. If one is not provided on the request, the server generates one automatically.
schema:
type: string
- name: User-Agent
in: header
description: The type of the client making the HTTP request.
schema:
type: string
- name: property
in: query
description: "Comma-separated filters. Multiple filters separated by commas can be passed. Examples below are given with unsafe HTML characters for clarity, but all content MUST be HTML escaped.\n\n Currently only `userId` is allowed in filtering count.\nExample: `property=userId=={USER_ID}`"
schema:
type: string
responses:
200:
x-summary: Success
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/template_count'
401:
x-summary: Unauthorized
description: Unauthorized
content: {}
404:
x-summary: Not found
description: Not Found
content: {}
'500':
x-summary: Internal server error
description: There was an internal server error. Try the request again in a few minutes, and contact Adobe Support if the problem persists.
content: {}
/query-templates/{queryTemplateId}:
get:
tags:
- Query Templates
summary: Retrieve a query template
operationId: retrieveQueryTemplate
description: This request retrieves the query template for the template ID provided in the request path.
parameters:
- name: Authorization
in: header
description: The access token which can be copied from your Experience Platform integration, prefixed with "Bearer " (for example, `Bearer {ACCESS_TOKEN}`). For more information on how to obtain this value, visit the documentation covering making API calls in the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
required: true
schema:
type: string
- name: x-gw-ims-org-id
in: header
description: The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the documentation covering making API calls in the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
required: true
schema:
type: string
- name: x-api-key
in: header
description: The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the documentation covering making API calls in the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
required: true
schema:
type: string
- name: x-sandbox-name
in: header
description: The name of the sandbox in which the operation will take place. See the [sandboxes overview documentation](https://adobe.com/go/sandbox-overview-en) for more information.
required: true
schema:
type: string
- name: x-request-id
in: header
description: An optional header that serves as a tracking ID for the request. If one is not provided on the request, the server generates one automatically.
schema:
type: string
- name: User-Agent
in: header
description: The type of the client making the HTTP request.
schema:
type: string
- name: queryTemplateId
in: path
description: The query template ID for the query template to be retrieved.
required: true
schema:
type: string
responses:
200:
x-summary: Success
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/query_template'
401:
x-summary: Unauthorized
description: Unauthorized
content: {}
404:
x-summary: Not found
description: Not Found
content: {}
'500':
x-summary: Internal server error
description: There was an internal server error. Try the request again in a few minutes, and contact Adobe Support if the problem persists.
content: {}
put:
tags:
- Query Templates
summary: Update a query template
operationId: updateQueryTemplate
description: This request updates the query template for the template ID provided in the request path.
parameters:
- name: Authorization
in: header
description: The access token which can be copied from your Experience Platform integration, prefixed with "Bearer " (for example, `Bearer {ACCESS_TOKEN}`). For more information on how to obtain this value, visit the documentation covering making API calls in the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
required: true
schema:
type: string
- name: x-gw-ims-org-id
in: header
description: The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the documentation covering making API calls in the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
required: true
schema:
type: string
- name: x-api-key
in: header
description: The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the documentation covering making API calls in the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
required: true
schema:
type: string
- name: x-sandbox-name
in: header
description: The name of the sandbox in which the operation will take place. See the [sandboxes overview documentation](https://adobe.com/go/sandbox-overview-en) for more information.
required: true
schema:
type: string
- name: x-request-id
in: header
description: An optional header that serves as a tracking ID for the request. If one is not provided on the request, the server generates one automatically.
schema:
type: string
- name: User-Agent
in: header
description: The type of the client making the HTTP request.
schema:
type: string
- name: queryTemplateId
in: path
description: The query template ID for the template to be updated.
required: true
schema:
type: string
requestBody:
description: Query template to be created.
content:
application/json:
schema:
$ref: '#/components/schemas/query_template_def'
required: true
responses:
202:
x-summary: Success
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/query_template'
401:
x-summary: Unauthorized
description: Unauthorized
content: {}
'500':
x-summary: Internal server error
description: There was an internal server error. Try the request again in a few minutes, and contact Adobe Support if the problem persists.
content: {}
x-codegen-request-body-name: queryTemplate
delete:
tags:
- Query Templates
summary: Delete a query template
operationId: deleteQueryTemplate
description: This request deletes the query template for the template ID provided in the request path.
parameters:
- name: Authorization
in: header
description: The access token which can be copied from your Experience Platform integration, prefixed with "Bearer " (for example, `Bearer {ACCESS_TOKEN}`). For more information on how to obtain this value, visit the documentation covering making API calls in the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
required: true
schema:
type: string
- name: x-gw-ims-org-id
in: header
description: The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the documentation covering making API calls in the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
required: true
schema:
type: string
- name: x-api-key
in: header
description: The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the documentation covering making API calls in the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
required: true
schema:
type: string
- name: x-sandbox-name
in: header
description: The name of the sandbox in which the operation will take place. See the [sandboxes overview documentation](https://adobe.com/go/sandbox-overview-en) for more information.
required: true
schema:
type: string
- name: x-request-id
in: header
description: An optional header that serves as a tracking ID for the request. If one is not provided on the request, the server generates one automatically.
schema:
type: string
- name: User-Agent
in: header
description: The type of the client making the HTTP request.
schema:
type: string
- name: queryTemplateId
in: path
description: The query template ID for the template to be deleted.
required: true
schema:
type: string
responses:
202:
x-summary: Success
description: Query Template Delete
content:
application/json:
schema:
$ref: '#/components/schemas/query_template_delete'
401:
x-summary: Unauthorized
description: Unauthorized
content: {}
404:
x-summary: Not found
description: Not Found
content: {}
'500':
x-summary: Internal server error
description: There was an internal server error. Try the request again in a few minutes, and contact Adobe Support if the problem persists.
content: {}
components:
schemas:
query_template_delete:
type: object
properties:
message:
type: string
description: A message to indicate the outcome of the request.
example: Deleted
statusCode:
type: string
description: The status code generated by the request.
example: 202
_page:
type: object
properties:
orderby:
type: string
description: The property by which this page is ordered.
example: -created
start:
type: string
description: The first value, in sorted order, of the orderby property on this page.
example: '2021-12-06T22:00:17.362Z'
next:
type: string
description: The start value for the next page.
example: '2022-11-22T00:52:34.839Z'
property:
type: string
description: The list of properties by which the result is filtered, if any. If the `property` query parameter is set when the query is issued, then it is returned in the `_page` object.
example: created>=2021-04-05T13:30:00Z,state==IN_PROGRESS
count:
type: integer
description: The number of items on the page.
example: 26
description: Pagination information for this resource. It contains a `count` property for the number of resources returned.
query_template:
type: object
properties:
sql:
type: string
description: The SQL query statement. You can use either standard SQL or include parameter replacements. To use a parameter replacement in the SQL you must prepend the parameter key with a `$`. For example, `$key`, and provide the parameters used in the SQL as JSON key value pairs in the `queryParameters` field.
example: SELECT $key from $key1 where $key > $key2;
name:
type: string
description: The name for the template.
example: Sample template query
id:
type: string
description: The ID of the query template.
example: f7cb5155-29da-4b95-6131-6c5beadjde7f
queryParameters:
type: object
properties:
key:
type: string
description: An example key value pair for a parameterized query.
example: value
key1:
type: string
description: An example key value pair for a parameterized query.
example: value1
key2:
type: string
description: An example key value pair for a parameterized query.
example: value2
description: A key value pairing for replacing values in the SQL. The key must be prepended with a `$`. For example, `SELECT column1 FROM table2 WHERE column1=$key;`. No value type checking will be done. This is required if using a parameter replacement.
updated:
type: string
description: The time in UTC format when query template was last updated.
example: '2022-11-21T21:50:01.469Z'
lastUpdatedBy:
type: string
description: The ID of the user who last updated the template.
example: '{USER_ID}'
userId:
type: string
description: The ID of the user who created the template.
example: '{USER_ID}'
_links:
$ref: '#/components/schemas/query_template_links'
description: Query Template Response.
next:
type: object
properties:
href:
type: string
description: A link to the next page of results.
example: https://platform.adobe.io/data/foundation/query/queries/alert-subscriptions?orderby=-created&page=2
description: Pre-constructed URI for the next page of results, if any exist.
query_list_template_links:
type: object
properties:
next:
$ref: '#/components/schemas/next'
prev:
$ref: '#/components/schemas/prev'
query_template_links:
type: object
properties:
self:
type: object
properties:
href:
type: string
description: The URI of this resource.
example: https://platform-va7.adobe.io/data/foundation/query/query-templates/2f560b99-abc0-4058-92dj-9408jaddcd71
method:
type: string
description: The HTTP method to use with the `href`.
example: GET
description: Contains the information required to access this resource.
update:
type: object
properties:
href:
type: string
description: The URI to update this resource.
example: https://platform-va7.adobe.io/data/foundation/query/query-templates/2f560b99-abc0-4058-92dj-9408jaddcd71
method:
type: string
description: The HTTP method to use with the `href`.
example: PUT
body:
type: string
description: The JSON payload to send to the `href`.
example: '{\"sql\" : \"new sql\", \"name\" : \"new name\"}'
description: Contains the information required to update this resource.
delete:
type: object
properties:
href:
type: string
description: The URI to delete this resource.
example: https://platform-va7.adobe.io/data/foundation/query/query-templates/2f560b99-abc0-4058-92dj-9408jaddcd71
method:
type: string
description: The HTTP method to use with the `href`.
example: DELETE
description: Contains the information required to delete this resource.
description: The object contains links to perform actions on this schedule run.
query_template_def:
required:
- name
- sql
type: object
properties:
sql:
type: string
description: You can either use standard SQL or a parameter replacement. To use a parameter replacement in the SQL you must prepend the parameter key with a `$`. For example, `$key`, and provide the parameters used in the SQL as JSON key value pairs in the `queryParameters` field. The values passed here will be the default parameters used in the template. If you want to override these parameters, you must override them in the POST request.
example: SELECT $key FROM $key1 WHERE $key > $key2;
queryParameters:
type: object
properties:
key:
type: string
description: A set of two linked data items. The key is a unique identifier for some item of data, and the value, is either the data that is identified or a pointer to the location of that data.
example: value
key1:
type: string
description: A set of two linked data items. The key is a unique identifier for some item of data, and the value, is either the data that is identified or a pointer to the location of that data.
example: value1
key2:
type: string
description: A set of two linked data items. The key is a unique identifier for some item of data, and the value, is either the data that is identified or a pointer to the location of that data.
example: value2
description: A key value pairing to replace values in the SQL statement. These are required if you are using parameter replacements. No value type checking will be done on these key value pairs.
name:
type: string
description: A descriptive and human readable name for the template.
example: Test Parameterized Query
description: A description of the query template to be submitted.
template_count:
type: object
properties:
totalCount:
type: integer
description: The total number of templates.
example: 52
version:
type: integer
description: The REST API version of this resource.
example: 1
description: Total Query Template count Response.
prev:
type: object
properties:
href:
type: string
description: A link to the previous page of results.
example: https://platform.adobe.io/data/foundation/query/queries/alert-subscriptions?orderby=-created&page=0
description: Pre-constructed URI for the previous page of results, if any exist.
query_template_list:
type: object
properties:
templates:
type: array
items:
$ref: '#/components/schemas/query_template'
_page:
$ref: '#/components/schemas/_page'
_links:
$ref: '#/components/schemas/query_list_template_links'
version:
type: integer
description: The REST API version of this resource.
description: List of queries