> For the complete documentation index, see [llms.txt](https://docs.mediarithmics.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mediarithmics.io/api-reference/datamart-operations/datamart-queries.md).

# Datamart Queries

Operations related to **OTQL Queries**, the query language for datamarts based on GraphQL. OTQL (Object Tree Query Language) enables querying user data across millions/billions of objects using a SELECT/FROM/WHERE pattern. Queries can be saved as objects for reuse in segments, exports, and other features with performance optimization through caching.

Relevant documentation:

* [OTQL queries](https://developer.mediarithmics.io/querying-your-data/otql-queries)
* [OTQL examples](https://developer.mediarithmics.io/querying-your-data/otql-examples)

## POST /datamarts/{datamart\_id}/queries/{query\_id}/segments/{segment\_id}/execution

> Execute an OTQL query with a segment id

```json
{"openapi":"3.1.1","info":{"title":"mediarithmics openapi API","version":"1.0.0"},"tags":[{"name":"Datamart queries","description":"Operations related to **OTQL Queries**, the query language for datamarts based on GraphQL. OTQL (Object Tree Query Language) enables querying user data across millions/billions of objects using a SELECT/FROM/WHERE pattern. Queries can be saved as objects for reuse in segments, exports, and other features with performance optimization through caching.\n\nRelevant documentation:\n- [OTQL queries](https://developer.mediarithmics.io/querying-your-data/otql-queries)\n- [OTQL examples](https://developer.mediarithmics.io/querying-your-data/otql-examples)\n"}],"servers":[{"url":"http://api.mediarithmics.local/v1","description":"Development server"},{"url":"https://api.mediarithmics.com/v1","description":"Production server"}],"paths":{"/datamarts/{datamart_id}/queries/{query_id}/segments/{segment_id}/execution":{"post":{"operationId":"executeOTQLWithSegmentId","tags":["Datamart queries"],"summary":"Execute an OTQL query with a segment id","responses":{"200":{"description":"Success !","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"$ref":"#/components/schemas/OTQLResult"}},"required":["data","status"]}}}},"400":{"$ref":"#/components/responses/error"},"401":{"$ref":"#/components/responses/error"},"403":{"$ref":"#/components/responses/error"},"404":{"$ref":"#/components/responses/error"},"500":{"$ref":"#/components/responses/error"},"503":{"$ref":"#/components/responses/error"}},"requestBody":{"description":"A raw query to execute if no queryId is provided","content":{"text/plain":{"schema":{"type":"string"}}},"required":false},"parameters":[{"schema":{"type":"integer","format":"int64"},"explode":false,"required":true,"style":"simple","description":"The datamart for which we register the query","in":"path","name":"datamart_id"},{"description":"The id of the query to execute. If provided, the body will be ignored","explode":false,"style":"simple","schema":{"type":"string"},"in":"path","required":true,"name":"query_id"},{"style":"simple","description":"The segment id to decorate que query with","in":"path","required":true,"schema":{"type":"string"},"explode":false,"name":"segment_id"},{"description":"The tree index to use. Default to USER_INDEX","schema":{"type":"string"},"style":"form","required":false,"explode":true,"name":"index_name","in":"query"},{"required":false,"style":"form","name":"limit","description":"In case of select queries, the limit of returned elements","explode":true,"in":"query","schema":{"type":"integer","format":"int32"}},{"name":"offset","required":false,"in":"query","description":"In case of select queries, the offset of the first element","style":"form","explode":true,"schema":{"type":"integer","format":"int32"}},{"description":"Precision used to execute the query. Default to FULL_PRECISION","name":"precision","style":"form","required":false,"in":"query","schema":{"$ref":"#/components/schemas/QueryPrecisionMode"},"explode":true},{"in":"query","schema":{"type":"boolean"},"name":"use_cache","explode":true,"description":"Use the cache","style":"form","required":false},{"in":"header","description":"Technical initiator","explode":false,"style":"simple","schema":{"type":"string"},"name":"X-Mics-Otql-Source","required":false}],"description":""}}},"components":{"schemas":{"OTQLResult":{"type":"object","properties":{"warning_message":{"type":"string","readOnly":false},"took":{"type":"integer","format":"int32","default":0,"readOnly":false},"limit":{"type":"integer","format":"int32","default":0,"readOnly":false},"cache_result_ts":{"type":"integer","format":"int64","default":0,"readOnly":false},"offset":{"type":"integer","format":"int32","default":0,"readOnly":false},"result_type":{"$ref":"#/components/schemas/OTQLResultType"},"rows":{"type":"string","readOnly":false},"precision":{"$ref":"#/components/schemas/QueryPrecisionMode"},"sampling_ratio":{"type":"number","format":"float","default":0,"readOnly":false},"cache_hit":{"type":"boolean","default":false,"readOnly":false},"timed_out":{"type":"boolean","default":false,"readOnly":false}},"required":["precision","result_type","rows"]},"OTQLResultType":{"type":"string","enum":["COUNT","AGGREGATION","SELECTION"],"readOnly":false},"QueryPrecisionMode":{"type":"string","enum":["FULL_PRECISION","MEDIUM_PRECISION","LOWER_PRECISION","defaultMode"],"readOnly":false},"errorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error_code":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTHORIZATION_ERROR","BAD_REQUEST_DATA","BAD_REQUEST_FORMAT","CONSTRAINT_VIOLATION_EXCEPTION","EMAIL_ALREADY_EXISTS","MAC_ERROR","RESOURCE_NOT_FOUND","SERVICE_UNAVAILABLE","TOKEN_ERROR"]},"error_id":{"type":"string"},"error":{"type":"string"}},"required":["error","error_code","error_id","status"]}},"responses":{"error":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorResponse"}}}}}}}
```

## POST /datamarts/{datamart\_id}/query\_executions/otql

> Execute an OTQL query

```json
{"openapi":"3.1.1","info":{"title":"mediarithmics openapi API","version":"1.0.0"},"tags":[{"name":"Mediarithmics most used API","description":"These operations where flagged by mediarithmics teams as most useful."},{"name":"Datamart queries","description":"Operations related to **OTQL Queries**, the query language for datamarts based on GraphQL. OTQL (Object Tree Query Language) enables querying user data across millions/billions of objects using a SELECT/FROM/WHERE pattern. Queries can be saved as objects for reuse in segments, exports, and other features with performance optimization through caching.\n\nRelevant documentation:\n- [OTQL queries](https://developer.mediarithmics.io/querying-your-data/otql-queries)\n- [OTQL examples](https://developer.mediarithmics.io/querying-your-data/otql-examples)\n"}],"servers":[{"url":"http://api.mediarithmics.local/v1","description":"Development server"},{"url":"https://api.mediarithmics.com/v1","description":"Production server"}],"paths":{"/datamarts/{datamart_id}/query_executions/otql":{"post":{"responses":{"200":{"description":"Success !","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"$ref":"#/components/schemas/OTQLResult"}},"required":["data","status"]}}}},"400":{"$ref":"#/components/responses/error"},"401":{"$ref":"#/components/responses/error"},"403":{"$ref":"#/components/responses/error"},"404":{"$ref":"#/components/responses/error"},"500":{"$ref":"#/components/responses/error"},"503":{"$ref":"#/components/responses/error"}},"operationId":"executeOTQL","description":"","parameters":[{"schema":{"type":"integer","format":"int64"},"explode":false,"description":"The datamart for which we register the query","required":true,"name":"datamart_id","style":"simple","in":"path"},{"schema":{"type":"string"},"required":false,"description":"The tree index to use. Default to USER_INDEX","name":"index_name","explode":true,"in":"query","style":"form"},{"required":false,"description":"The id of the query to execute. If provided, the body will be ignored","schema":{"type":"string"},"style":"form","name":"queryId","explode":true,"in":"query"},{"explode":true,"description":"In case of select queries, the limit of returned elements","style":"form","in":"query","name":"limit","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"offset","explode":true,"schema":{"type":"integer","format":"int32"},"description":"In case of select queries, the offset of the first element","required":false,"style":"form","in":"query"},{"in":"query","explode":true,"required":false,"schema":{"$ref":"#/components/schemas/QueryPrecisionMode"},"style":"form","name":"precision","description":"Precision used to execute the query. Default to FULL_PRECISION"},{"schema":{"type":"boolean"},"in":"query","explode":true,"style":"form","description":"Use the cache","required":false,"name":"use_cache"},{"description":"Technical initiator","in":"header","name":"X-Mics-Otql-Source","schema":{"type":"string"},"style":"simple","required":false,"explode":false}],"requestBody":{"description":"A raw query to execute if no queryId is provided","content":{"text/plain":{"schema":{"type":"string"}}},"required":false},"summary":"Execute an OTQL query","tags":["Datamart queries","Mediarithmics most used API"]}}},"components":{"schemas":{"OTQLResult":{"type":"object","properties":{"warning_message":{"type":"string","readOnly":false},"took":{"type":"integer","format":"int32","default":0,"readOnly":false},"limit":{"type":"integer","format":"int32","default":0,"readOnly":false},"cache_result_ts":{"type":"integer","format":"int64","default":0,"readOnly":false},"offset":{"type":"integer","format":"int32","default":0,"readOnly":false},"result_type":{"$ref":"#/components/schemas/OTQLResultType"},"rows":{"type":"string","readOnly":false},"precision":{"$ref":"#/components/schemas/QueryPrecisionMode"},"sampling_ratio":{"type":"number","format":"float","default":0,"readOnly":false},"cache_hit":{"type":"boolean","default":false,"readOnly":false},"timed_out":{"type":"boolean","default":false,"readOnly":false}},"required":["precision","result_type","rows"]},"OTQLResultType":{"type":"string","enum":["COUNT","AGGREGATION","SELECTION"],"readOnly":false},"QueryPrecisionMode":{"type":"string","enum":["FULL_PRECISION","MEDIUM_PRECISION","LOWER_PRECISION","defaultMode"],"readOnly":false},"errorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error_code":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTHORIZATION_ERROR","BAD_REQUEST_DATA","BAD_REQUEST_FORMAT","CONSTRAINT_VIOLATION_EXCEPTION","EMAIL_ALREADY_EXISTS","MAC_ERROR","RESOURCE_NOT_FOUND","SERVICE_UNAVAILABLE","TOKEN_ERROR"]},"error_id":{"type":"string"},"error":{"type":"string"}},"required":["error","error_code","error_id","status"]}},"responses":{"error":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorResponse"}}}}}}}
```

## POST /datamarts/{datamart\_id}/query\_executions\_async/otql

> register a query

```json
{"openapi":"3.1.1","info":{"title":"mediarithmics openapi API","version":"1.0.0"},"tags":[{"name":"Datamart queries","description":"Operations related to **OTQL Queries**, the query language for datamarts based on GraphQL. OTQL (Object Tree Query Language) enables querying user data across millions/billions of objects using a SELECT/FROM/WHERE pattern. Queries can be saved as objects for reuse in segments, exports, and other features with performance optimization through caching.\n\nRelevant documentation:\n- [OTQL queries](https://developer.mediarithmics.io/querying-your-data/otql-queries)\n- [OTQL examples](https://developer.mediarithmics.io/querying-your-data/otql-examples)\n"}],"servers":[{"url":"http://api.mediarithmics.local/v1","description":"Development server"},{"url":"https://api.mediarithmics.com/v1","description":"Production server"}],"paths":{"/datamarts/{datamart_id}/query_executions_async/otql":{"post":{"parameters":[{"name":"datamart_id","in":"path","required":true,"description":"The datamart for which we register the query","explode":false,"schema":{"type":"string"},"style":"simple"},{"in":"query","required":false,"schema":{"type":"string"},"style":"form","description":"The schema against which we want to run the query (default to live)","explode":true,"name":"schema_id"},{"in":"query","schema":{"type":"string"},"required":false,"name":"tree_index_id","style":"form","description":"The tree index on which we want to run the query (default to live)","explode":true},{"required":false,"name":"query_engine_type","style":"form","description":"The engine type to run the query on - default to TREE_INDEX","schema":{"$ref":"#/components/schemas/QueryEngineType"},"explode":true,"in":"query"},{"in":"query","name":"data_warehouse_id","required":false,"explode":true,"style":"form","schema":{"type":"string"},"description":"The data warehouse id, required for SQL queries"},{"schema":{"type":"string"},"description":"Technical initiator","name":"X-Mics-Otql-Source","explode":false,"in":"header","style":"simple","required":false}],"summary":"register a query","operationId":"registerQuery","responses":{"200":{"description":"Success !","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"$ref":"#/components/schemas/QueryRegisteringResponse"}},"required":["data","status"]}}}},"400":{"$ref":"#/components/responses/error"},"401":{"$ref":"#/components/responses/error"},"403":{"$ref":"#/components/responses/error"},"404":{"$ref":"#/components/responses/error"},"500":{"$ref":"#/components/responses/error"},"503":{"$ref":"#/components/responses/error"}},"description":"","tags":["Datamart queries"],"requestBody":{"description":"The query to register","content":{"text/plain":{"schema":{"type":"string"}}},"required":true}}}},"components":{"schemas":{"QueryEngineType":{"type":"string","enum":["SQL","TREE_INDEX"],"readOnly":false},"QueryRegisteringResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid","readOnly":false},"validation":{"$ref":"#/components/schemas/QueryValidationResponse"}},"required":["validation"]},"QueryValidationResponse":{"discriminator":{"propertyName":"type","mapping":{"SUCCESS":"#/components/schemas/QueryValidationSuccessResponse","PARSING_ERROR":"#/components/schemas/QueryValidationParsingErrorResponse","VALIDATION_ERROR":"#/components/schemas/QueryValidationErrorResponse"}},"oneOf":[{"$ref":"#/components/schemas/QueryValidationSuccessResponse"},{"$ref":"#/components/schemas/QueryValidationParsingErrorResponse"},{"$ref":"#/components/schemas/QueryValidationErrorResponse"}],"properties":{"type":{"type":"string","enum":["SUCCESS","PARSING_ERROR","VALIDATION_ERROR"]}},"required":["type"]},"QueryValidationSuccessResponse":{"type":"object","properties":{"validation":{"$ref":"#/components/schemas/OTQLValidationSuccess"}},"required":["validation"]},"OTQLValidationSuccess":{"type":"object","properties":{"parameters":{"type":"array","items":{"$ref":"#/components/schemas/OTQLTypedParameter"},"readOnly":false}},"required":["parameters"]},"OTQLTypedParameter":{"type":"object","properties":{"reference_model_type":{"type":"string","readOnly":false},"parameter_name":{"type":"string","readOnly":false},"type":{"type":"string","readOnly":false},"container_type":{"type":"string","readOnly":false},"reference_type":{"type":"string","readOnly":false},"directive":{"type":"string","readOnly":false},"data_type":{"type":"string","readOnly":false},"path":{"type":"array","items":{"type":"string","readOnly":false},"readOnly":false},"field_name":{"type":"string","readOnly":false}},"required":["field_name","parameter_name","path","type"]},"QueryValidationParsingErrorResponse":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/QueryParsingError"}},"required":["error"]},"QueryParsingError":{"type":"object","properties":{"message":{"type":"string","readOnly":false},"position":{"$ref":"#/components/schemas/PositionResource"}},"required":["message","position"]},"PositionResource":{"type":"object","properties":{"row":{"type":"integer","format":"int32","default":0,"readOnly":false},"col":{"type":"integer","format":"int32","default":0,"readOnly":false}},"required":["col","row"]},"QueryValidationErrorResponse":{"type":"object","properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/OTQLValidationErrorResource"},"readOnly":false}},"required":["errors"]},"OTQLValidationErrorResource":{"type":"object","properties":{"message":{"type":"string","readOnly":false},"position":{"$ref":"#/components/schemas/PositionResource"},"error_type":{"type":"string","readOnly":false}},"required":["error_type","message"]},"errorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error_code":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTHORIZATION_ERROR","BAD_REQUEST_DATA","BAD_REQUEST_FORMAT","CONSTRAINT_VIOLATION_EXCEPTION","EMAIL_ALREADY_EXISTS","MAC_ERROR","RESOURCE_NOT_FOUND","SERVICE_UNAVAILABLE","TOKEN_ERROR"]},"error_id":{"type":"string"},"error":{"type":"string"}},"required":["error","error_code","error_id","status"]}},"responses":{"error":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorResponse"}}}}}}}
```

## POST /datamarts/{datamart\_id}/query\_translations

> Translate a Json type query to an output\_type query

```json
{"openapi":"3.1.1","info":{"title":"mediarithmics openapi API","version":"1.0.0"},"tags":[{"name":"Datamart queries","description":"Operations related to **OTQL Queries**, the query language for datamarts based on GraphQL. OTQL (Object Tree Query Language) enables querying user data across millions/billions of objects using a SELECT/FROM/WHERE pattern. Queries can be saved as objects for reuse in segments, exports, and other features with performance optimization through caching.\n\nRelevant documentation:\n- [OTQL queries](https://developer.mediarithmics.io/querying-your-data/otql-queries)\n- [OTQL examples](https://developer.mediarithmics.io/querying-your-data/otql-examples)\n"}],"servers":[{"url":"http://api.mediarithmics.local/v1","description":"Development server"},{"url":"https://api.mediarithmics.com/v1","description":"Production server"}],"paths":{"/datamarts/{datamart_id}/query_translations":{"post":{"description":"","parameters":[{"schema":{"type":"string"},"explode":false,"required":true,"name":"datamart_id","style":"simple","in":"path","description":"Datamart id"}],"summary":"Translate a Json type query to an output_type query","operationId":"translateQuery","requestBody":{"description":"The query to translate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryTranslationResource"}}},"required":true},"responses":{"200":{"description":"Success !","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"$ref":"#/components/schemas/QueryTranslationResource"}},"required":["data","status"]}}}},"400":{"$ref":"#/components/responses/error"},"401":{"$ref":"#/components/responses/error"},"403":{"$ref":"#/components/responses/error"},"404":{"$ref":"#/components/responses/error"},"500":{"$ref":"#/components/responses/error"},"503":{"$ref":"#/components/responses/error"}},"tags":["Datamart queries"]}}},"components":{"schemas":{"QueryTranslationResource":{"type":"object","properties":{"output_query_language_subtype":{"$ref":"#/components/schemas/QueryLanguageSubtype"},"input_query_language":{"$ref":"#/components/schemas/QueryLanguage"},"output_query_language":{"$ref":"#/components/schemas/QueryLanguage"},"output_query_text":{"type":"string","readOnly":true},"input_query_text":{"type":"string","readOnly":false},"input_query_language_subtype":{"$ref":"#/components/schemas/QueryLanguageSubtype"}},"required":["input_query_language","input_query_text","output_query_language","output_query_text"]},"QueryLanguageSubtype":{"type":"string","enum":["PARAMETRIC"],"readOnly":false},"QueryLanguage":{"type":"string","enum":["SELECTORQL","JSON_OTQL","OTQL","GRAPHQL","SQL"],"readOnly":false},"errorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error_code":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTHORIZATION_ERROR","BAD_REQUEST_DATA","BAD_REQUEST_FORMAT","CONSTRAINT_VIOLATION_EXCEPTION","EMAIL_ALREADY_EXISTS","MAC_ERROR","RESOURCE_NOT_FOUND","SERVICE_UNAVAILABLE","TOKEN_ERROR"]},"error_id":{"type":"string"},"error":{"type":"string"}},"required":["error","error_code","error_id","status"]}},"responses":{"error":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorResponse"}}}}}}}
```

## POST /datamarts/{datamart\_id}/query\_check/otql

> Check OTQL queries

```json
{"openapi":"3.1.1","info":{"title":"mediarithmics openapi API","version":"1.0.0"},"tags":[{"name":"Datamart queries","description":"Operations related to **OTQL Queries**, the query language for datamarts based on GraphQL. OTQL (Object Tree Query Language) enables querying user data across millions/billions of objects using a SELECT/FROM/WHERE pattern. Queries can be saved as objects for reuse in segments, exports, and other features with performance optimization through caching.\n\nRelevant documentation:\n- [OTQL queries](https://developer.mediarithmics.io/querying-your-data/otql-queries)\n- [OTQL examples](https://developer.mediarithmics.io/querying-your-data/otql-examples)\n"}],"servers":[{"url":"http://api.mediarithmics.local/v1","description":"Development server"},{"url":"https://api.mediarithmics.com/v1","description":"Production server"}],"paths":{"/datamarts/{datamart_id}/query_check/otql":{"post":{"responses":{"200":{"description":"Success !","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"$ref":"#/components/schemas/QueryValidationResponse"}},"required":["data","status"]}}}},"400":{"$ref":"#/components/responses/error"},"401":{"$ref":"#/components/responses/error"},"403":{"$ref":"#/components/responses/error"},"404":{"$ref":"#/components/responses/error"},"500":{"$ref":"#/components/responses/error"},"503":{"$ref":"#/components/responses/error"}},"operationId":"queryCheck","parameters":[{"style":"simple","schema":{"type":"string"},"in":"path","description":"Datamart id","explode":false,"required":true,"name":"datamart_id"}],"tags":["Datamart queries"],"requestBody":{"description":"The query to check on","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryValidationRequest"}}},"required":true},"summary":"Check OTQL queries","description":""}}},"components":{"schemas":{"QueryValidationResponse":{"discriminator":{"propertyName":"type","mapping":{"SUCCESS":"#/components/schemas/QueryValidationSuccessResponse","PARSING_ERROR":"#/components/schemas/QueryValidationParsingErrorResponse","VALIDATION_ERROR":"#/components/schemas/QueryValidationErrorResponse"}},"oneOf":[{"$ref":"#/components/schemas/QueryValidationSuccessResponse"},{"$ref":"#/components/schemas/QueryValidationParsingErrorResponse"},{"$ref":"#/components/schemas/QueryValidationErrorResponse"}],"properties":{"type":{"type":"string","enum":["SUCCESS","PARSING_ERROR","VALIDATION_ERROR"]}},"required":["type"]},"QueryValidationSuccessResponse":{"type":"object","properties":{"validation":{"$ref":"#/components/schemas/OTQLValidationSuccess"}},"required":["validation"]},"OTQLValidationSuccess":{"type":"object","properties":{"parameters":{"type":"array","items":{"$ref":"#/components/schemas/OTQLTypedParameter"},"readOnly":false}},"required":["parameters"]},"OTQLTypedParameter":{"type":"object","properties":{"reference_model_type":{"type":"string","readOnly":false},"parameter_name":{"type":"string","readOnly":false},"type":{"type":"string","readOnly":false},"container_type":{"type":"string","readOnly":false},"reference_type":{"type":"string","readOnly":false},"directive":{"type":"string","readOnly":false},"data_type":{"type":"string","readOnly":false},"path":{"type":"array","items":{"type":"string","readOnly":false},"readOnly":false},"field_name":{"type":"string","readOnly":false}},"required":["field_name","parameter_name","path","type"]},"QueryValidationParsingErrorResponse":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/QueryParsingError"}},"required":["error"]},"QueryParsingError":{"type":"object","properties":{"message":{"type":"string","readOnly":false},"position":{"$ref":"#/components/schemas/PositionResource"}},"required":["message","position"]},"PositionResource":{"type":"object","properties":{"row":{"type":"integer","format":"int32","default":0,"readOnly":false},"col":{"type":"integer","format":"int32","default":0,"readOnly":false}},"required":["col","row"]},"QueryValidationErrorResponse":{"type":"object","properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/OTQLValidationErrorResource"},"readOnly":false}},"required":["errors"]},"OTQLValidationErrorResource":{"type":"object","properties":{"message":{"type":"string","readOnly":false},"position":{"$ref":"#/components/schemas/PositionResource"},"error_type":{"type":"string","readOnly":false}},"required":["error_type","message"]},"errorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error_code":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTHORIZATION_ERROR","BAD_REQUEST_DATA","BAD_REQUEST_FORMAT","CONSTRAINT_VIOLATION_EXCEPTION","EMAIL_ALREADY_EXISTS","MAC_ERROR","RESOURCE_NOT_FOUND","SERVICE_UNAVAILABLE","TOKEN_ERROR"]},"error_id":{"type":"string"},"error":{"type":"string"}},"required":["error","error_code","error_id","status"]},"QueryValidationRequest":{"type":"object","properties":{"query":{"type":"string","readOnly":false}},"required":["query"]}},"responses":{"error":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorResponse"}}}}}}}
```

## POST /datamarts/{datamart\_id}/query\_autocomplete/otql

> Autocomplete OTQL queries

```json
{"openapi":"3.1.1","info":{"title":"mediarithmics openapi API","version":"1.0.0"},"tags":[{"name":"Datamart queries","description":"Operations related to **OTQL Queries**, the query language for datamarts based on GraphQL. OTQL (Object Tree Query Language) enables querying user data across millions/billions of objects using a SELECT/FROM/WHERE pattern. Queries can be saved as objects for reuse in segments, exports, and other features with performance optimization through caching.\n\nRelevant documentation:\n- [OTQL queries](https://developer.mediarithmics.io/querying-your-data/otql-queries)\n- [OTQL examples](https://developer.mediarithmics.io/querying-your-data/otql-examples)\n"}],"servers":[{"url":"http://api.mediarithmics.local/v1","description":"Development server"},{"url":"https://api.mediarithmics.com/v1","description":"Production server"}],"paths":{"/datamarts/{datamart_id}/query_autocomplete/otql":{"post":{"description":"","requestBody":{"description":"The query to autocomplete and the cursor position","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OTQLAutoCompleteRequestResource"}}},"required":true},"tags":["Datamart queries"],"parameters":[{"required":true,"style":"simple","schema":{"type":"string"},"explode":false,"description":"Datamart id","name":"datamart_id","in":"path"}],"operationId":"autocomplete","summary":"Autocomplete OTQL queries","responses":{"200":{"description":"Success !","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"first_result":{"type":"integer"},"total":{"type":"integer"},"max_results":{"type":"integer"},"data":{"type":"array","items":{"$ref":"#/components/schemas/AutoCompleteResource"}},"count":{"type":"integer"}},"required":["count","data","first_result","max_results","status","total"]}}}},"400":{"$ref":"#/components/responses/error"},"401":{"$ref":"#/components/responses/error"},"403":{"$ref":"#/components/responses/error"},"404":{"$ref":"#/components/responses/error"},"500":{"$ref":"#/components/responses/error"},"503":{"$ref":"#/components/responses/error"}}}}},"components":{"schemas":{"OTQLAutoCompleteRequestResource":{"type":"object","properties":{"query":{"type":"string","readOnly":false},"position":{"$ref":"#/components/schemas/PositionResource"}},"required":["position","query"]},"PositionResource":{"type":"object","properties":{"row":{"type":"integer","format":"int32","default":0,"readOnly":false},"col":{"type":"integer","format":"int32","default":0,"readOnly":false}},"required":["col","row"]},"AutoCompleteResource":{"discriminator":{"propertyName":"type","mapping":{"FIELD_AUTO_COMPLETE":"#/components/schemas/FieldAutoComplete","DIRECTIVE_AUTO_COMPLETE":"#/components/schemas/DirectiveAutoComplete","DIRECTIVE_ARGUMENT_AUTO_COMPLETE":"#/components/schemas/DirectiveArgumentAutoComplete"}},"oneOf":[{"$ref":"#/components/schemas/FieldAutoComplete"},{"$ref":"#/components/schemas/DirectiveAutoComplete"},{"$ref":"#/components/schemas/DirectiveArgumentAutoComplete"}],"properties":{"type":{"type":"string","enum":["FIELD_AUTO_COMPLETE","DIRECTIVE_AUTO_COMPLETE","DIRECTIVE_ARGUMENT_AUTO_COMPLETE"]}},"required":["type"]},"FieldAutoComplete":{"type":"object","properties":{"object_type_name":{"type":"string","readOnly":false},"field_name":{"type":"string","readOnly":false}},"required":["field_name","object_type_name"]},"DirectiveAutoComplete":{"type":"object","properties":{"directive":{"type":"string","readOnly":false}},"required":["directive"]},"DirectiveArgumentAutoComplete":{"type":"object","properties":{"directive":{"type":"string","readOnly":false},"arg_name":{"type":"string","readOnly":false},"arg_type":{"type":"string","readOnly":false}},"required":["arg_name","directive"]},"errorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error_code":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTHORIZATION_ERROR","BAD_REQUEST_DATA","BAD_REQUEST_FORMAT","CONSTRAINT_VIOLATION_EXCEPTION","EMAIL_ALREADY_EXISTS","MAC_ERROR","RESOURCE_NOT_FOUND","SERVICE_UNAVAILABLE","TOKEN_ERROR"]},"error_id":{"type":"string"},"error":{"type":"string"}},"required":["error","error_code","error_id","status"]}},"responses":{"error":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorResponse"}}}}}}}
```

## GET /datamarts/{datamart\_id}/query\_executions\_async/otql/{query\_id}

> Get the result of a query

```json
{"openapi":"3.1.1","info":{"title":"mediarithmics openapi API","version":"1.0.0"},"tags":[{"name":"Datamart queries","description":"Operations related to **OTQL Queries**, the query language for datamarts based on GraphQL. OTQL (Object Tree Query Language) enables querying user data across millions/billions of objects using a SELECT/FROM/WHERE pattern. Queries can be saved as objects for reuse in segments, exports, and other features with performance optimization through caching.\n\nRelevant documentation:\n- [OTQL queries](https://developer.mediarithmics.io/querying-your-data/otql-queries)\n- [OTQL examples](https://developer.mediarithmics.io/querying-your-data/otql-examples)\n"}],"servers":[{"url":"http://api.mediarithmics.local/v1","description":"Development server"},{"url":"https://api.mediarithmics.com/v1","description":"Production server"}],"paths":{"/datamarts/{datamart_id}/query_executions_async/otql/{query_id}":{"get":{"tags":["Datamart queries"],"parameters":[{"description":"The datamart for which we register the query","explode":false,"schema":{"type":"string"},"required":true,"name":"datamart_id","style":"simple","in":"path"},{"in":"path","schema":{"type":"string","format":"uuid"},"name":"query_id","style":"simple","required":true,"explode":false},{"explode":true,"style":"form","in":"query","name":"answer_timeout_ms","schema":{"type":"integer","format":"int32"},"description":"max time to wait before answering (in milliseconds), either with the result or a running execution","required":false}],"summary":"Get the result of a query","responses":{"200":{"description":"Success !","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"$ref":"#/components/schemas/ObjectTreeQueryResultPublicResponse"}},"required":["data","status"]}}}},"400":{"$ref":"#/components/responses/error"},"401":{"$ref":"#/components/responses/error"},"403":{"$ref":"#/components/responses/error"},"404":{"$ref":"#/components/responses/error"},"500":{"$ref":"#/components/responses/error"},"503":{"$ref":"#/components/responses/error"}},"operationId":"getResult","description":""}}},"components":{"schemas":{"ObjectTreeQueryResultPublicResponse":{"discriminator":{"propertyName":"type","mapping":{"NO_RESULT":"#/components/schemas/NoResult","COUNT_RESULT":"#/components/schemas/CountResult","ERROR_RESULT":"#/components/schemas/ErrorResult","AGGREGATION_RESULT":"#/components/schemas/AggregationResult","SELECTION_RESULT":"#/components/schemas/SelectionResult"}},"oneOf":[{"$ref":"#/components/schemas/ErrorResult"},{"$ref":"#/components/schemas/CountResult"},{"$ref":"#/components/schemas/SelectionResult"},{"$ref":"#/components/schemas/NoResult"},{"$ref":"#/components/schemas/AggregationResult"}],"properties":{"type":{"type":"string","enum":["ERROR_RESULT","COUNT_RESULT","SELECTION_RESULT","NO_RESULT","AGGREGATION_RESULT"]}},"required":["type"]},"ErrorResult":{"type":"object","properties":{"query_status":{"$ref":"#/components/schemas/OTQLRequestStatus"},"error":{"$ref":"#/components/schemas/OTQLPublicErrorTypes"},"retryable":{"type":"boolean","default":false,"readOnly":false}},"required":["error","query_status"]},"OTQLRequestStatus":{"type":"string","enum":["REGISTERED","PENDING","RUNNING","CANCELLED_BY_USER","CANCELLED_BY_PROXY","TIMEOUT","FAILED","SUCCESSFUL","LOST","publicRunning","publicCancelled","ended"],"readOnly":false},"OTQLPublicErrorTypes":{"type":"string","enum":["TREE_INDEX_ERROR","TIMEOUT","UPDATE_TO_RUNNING_EXCEPTION","UNDEFINED_ERROR","TOO_MANY_RESULTS","TIME_FRAME_TOO_WIDE"],"readOnly":false},"CountResult":{"allOf":[{"$ref":"#/components/schemas/Result"},{"type":"object","properties":{"took":{"type":"integer","format":"int64","default":0,"readOnly":false},"precision":{"$ref":"#/components/schemas/QueryPrecisionMode"},"query_status":{"$ref":"#/components/schemas/OTQLRequestStatus"},"cache_hit":{"type":"boolean","default":false,"readOnly":false},"sampling_ratio":{"type":"number","format":"float","default":0,"readOnly":false},"count":{"type":"integer","format":"int64","default":0,"readOnly":false},"cache_result_ts":{"type":"integer","format":"int64","default":0,"readOnly":false}},"required":["cache_hit","count","precision","query_status"]}]},"Result":{"type":"object"},"QueryPrecisionMode":{"type":"string","enum":["FULL_PRECISION","MEDIUM_PRECISION","LOWER_PRECISION","defaultMode"],"readOnly":false},"SelectionResult":{"allOf":[{"$ref":"#/components/schemas/Result"},{"type":"object","properties":{"cache_hit":{"type":"boolean","default":false,"readOnly":false},"query_status":{"$ref":"#/components/schemas/OTQLRequestStatus"},"offset":{"type":"integer","format":"int64","default":0,"readOnly":false},"limit":{"type":"integer","format":"int32","default":0,"readOnly":false},"result":{"type":"string","readOnly":false},"count":{"type":"integer","format":"int64","default":0,"readOnly":false},"cache_result_ts":{"type":"integer","format":"int64","default":0,"readOnly":false},"took":{"type":"integer","format":"int64","default":0,"readOnly":false}},"required":["cache_hit","count","query_status","result"]}]},"NoResult":{"type":"object","properties":{"query_status":{"$ref":"#/components/schemas/OTQLRequestStatus"},"retryable":{"type":"boolean","default":false,"readOnly":false}},"required":["query_status"]},"AggregationResult":{"allOf":[{"$ref":"#/components/schemas/Result"},{"type":"object","properties":{"cache_result_ts":{"type":"integer","format":"int64","default":0,"readOnly":false},"query_status":{"$ref":"#/components/schemas/OTQLRequestStatus"},"count":{"type":"integer","format":"int64","default":0,"readOnly":false},"precision":{"$ref":"#/components/schemas/QueryPrecisionMode"},"aggregation":{"$ref":"#/components/schemas/OTQLAggregations"},"sampling_ratio":{"type":"number","format":"float","default":0,"readOnly":false},"took":{"type":"integer","format":"int64","default":0,"readOnly":false},"cache_hit":{"type":"boolean","default":false,"readOnly":false}},"required":["aggregation","cache_hit","count","precision","query_status"]}]},"OTQLAggregations":{"type":"object","properties":{"bucket_aggregations":{"type":"array","items":{"$ref":"#/components/schemas/OTQLBuckets"},"readOnly":false},"metric_aggregations":{"type":"array","items":{"$ref":"#/components/schemas/OTQLMetric"},"readOnly":false}},"required":["bucket_aggregations","metric_aggregations"]},"OTQLBuckets":{"type":"object","properties":{"name":{"type":"string","readOnly":false},"field_name":{"type":"string","readOnly":false},"bucket_type":{"type":"string","readOnly":false},"path":{"type":"string","readOnly":false},"buckets":{"type":"array","items":{"$ref":"#/components/schemas/OTQLBucket"},"readOnly":false},"type":{"type":"string","readOnly":false}},"required":["bucket_type","buckets","field_name","name","type"]},"OTQLBucket":{"type":"object","properties":{"key":{"type":"string","readOnly":false},"count":{"type":"integer","format":"int64","default":0,"readOnly":false},"aggregations":{"$ref":"#/components/schemas/OTQLAggregations"}},"required":["count","key"]},"OTQLMetric":{"discriminator":{"propertyName":"type","mapping":{"OTQL_SINGLE_METRIC":"#/components/schemas/OTQLSingleMetric","OTQL_AGGREGATION_METRIC":"#/components/schemas/OTQLMultipleMetric"}},"oneOf":[{"$ref":"#/components/schemas/OTQLSingleMetric"},{"$ref":"#/components/schemas/OTQLMultipleMetric"}],"properties":{"type":{"type":"string","enum":["OTQL_SINGLE_METRIC","OTQL_AGGREGATION_METRIC"]}},"required":["type"]},"OTQLSingleMetric":{"type":"object","properties":{"path":{"type":"string","readOnly":false},"name":{"type":"string","readOnly":false},"field_name":{"type":"string","readOnly":false},"metric_type":{"type":"string","readOnly":false},"value":{"type":"number","format":"float","default":0,"readOnly":false}},"required":["field_name","metric_type","name"]},"OTQLMultipleMetric":{"type":"object","properties":{"name":{"type":"string","readOnly":false},"path":{"type":"string","readOnly":false},"metric_type":{"type":"string","readOnly":false},"field_name":{"type":"string","readOnly":false},"value":{"type":"array","items":{"type":"number","format":"float","default":0,"readOnly":false},"readOnly":false}},"required":["field_name","metric_type","name","value"]},"errorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error_code":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTHORIZATION_ERROR","BAD_REQUEST_DATA","BAD_REQUEST_FORMAT","CONSTRAINT_VIOLATION_EXCEPTION","EMAIL_ALREADY_EXISTS","MAC_ERROR","RESOURCE_NOT_FOUND","SERVICE_UNAVAILABLE","TOKEN_ERROR"]},"error_id":{"type":"string"},"error":{"type":"string"}},"required":["error","error_code","error_id","status"]}},"responses":{"error":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorResponse"}}}}}}}
```

## PUT /datamarts/{datamart\_id}/query\_executions\_async/otql/{query\_id}

> Run asynchronously a submitted query

```json
{"openapi":"3.1.1","info":{"title":"mediarithmics openapi API","version":"1.0.0"},"tags":[{"name":"Datamart queries","description":"Operations related to **OTQL Queries**, the query language for datamarts based on GraphQL. OTQL (Object Tree Query Language) enables querying user data across millions/billions of objects using a SELECT/FROM/WHERE pattern. Queries can be saved as objects for reuse in segments, exports, and other features with performance optimization through caching.\n\nRelevant documentation:\n- [OTQL queries](https://developer.mediarithmics.io/querying-your-data/otql-queries)\n- [OTQL examples](https://developer.mediarithmics.io/querying-your-data/otql-examples)\n"}],"servers":[{"url":"http://api.mediarithmics.local/v1","description":"Development server"},{"url":"https://api.mediarithmics.com/v1","description":"Production server"}],"paths":{"/datamarts/{datamart_id}/query_executions_async/otql/{query_id}":{"put":{"operationId":"runAsync","parameters":[{"explode":false,"style":"simple","description":"The datamart for which we register the query","required":true,"name":"datamart_id","in":"path","schema":{"type":"string"}},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"query_id","explode":false,"style":"simple","required":true},{"style":"form","schema":{"type":"boolean"},"explode":true,"in":"query","name":"use_cache","required":false},{"schema":{"type":"integer","format":"int32"},"explode":true,"style":"form","description":"max time to wait before answering (in milliseconds), either with the result or a running execution","required":false,"in":"query","name":"answer_timeout_ms"}],"description":"","summary":"Run asynchronously a submitted query","tags":["Datamart queries"],"responses":{"200":{"description":"Success !","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"$ref":"#/components/schemas/ObjectTreeQueryResultPublicResponse"}},"required":["data","status"]}}}},"400":{"$ref":"#/components/responses/error"},"401":{"$ref":"#/components/responses/error"},"403":{"$ref":"#/components/responses/error"},"404":{"$ref":"#/components/responses/error"},"500":{"$ref":"#/components/responses/error"},"503":{"$ref":"#/components/responses/error"}}}}},"components":{"schemas":{"ObjectTreeQueryResultPublicResponse":{"discriminator":{"propertyName":"type","mapping":{"NO_RESULT":"#/components/schemas/NoResult","COUNT_RESULT":"#/components/schemas/CountResult","ERROR_RESULT":"#/components/schemas/ErrorResult","AGGREGATION_RESULT":"#/components/schemas/AggregationResult","SELECTION_RESULT":"#/components/schemas/SelectionResult"}},"oneOf":[{"$ref":"#/components/schemas/ErrorResult"},{"$ref":"#/components/schemas/CountResult"},{"$ref":"#/components/schemas/SelectionResult"},{"$ref":"#/components/schemas/NoResult"},{"$ref":"#/components/schemas/AggregationResult"}],"properties":{"type":{"type":"string","enum":["ERROR_RESULT","COUNT_RESULT","SELECTION_RESULT","NO_RESULT","AGGREGATION_RESULT"]}},"required":["type"]},"ErrorResult":{"type":"object","properties":{"query_status":{"$ref":"#/components/schemas/OTQLRequestStatus"},"error":{"$ref":"#/components/schemas/OTQLPublicErrorTypes"},"retryable":{"type":"boolean","default":false,"readOnly":false}},"required":["error","query_status"]},"OTQLRequestStatus":{"type":"string","enum":["REGISTERED","PENDING","RUNNING","CANCELLED_BY_USER","CANCELLED_BY_PROXY","TIMEOUT","FAILED","SUCCESSFUL","LOST","publicRunning","publicCancelled","ended"],"readOnly":false},"OTQLPublicErrorTypes":{"type":"string","enum":["TREE_INDEX_ERROR","TIMEOUT","UPDATE_TO_RUNNING_EXCEPTION","UNDEFINED_ERROR","TOO_MANY_RESULTS","TIME_FRAME_TOO_WIDE"],"readOnly":false},"CountResult":{"allOf":[{"$ref":"#/components/schemas/Result"},{"type":"object","properties":{"took":{"type":"integer","format":"int64","default":0,"readOnly":false},"precision":{"$ref":"#/components/schemas/QueryPrecisionMode"},"query_status":{"$ref":"#/components/schemas/OTQLRequestStatus"},"cache_hit":{"type":"boolean","default":false,"readOnly":false},"sampling_ratio":{"type":"number","format":"float","default":0,"readOnly":false},"count":{"type":"integer","format":"int64","default":0,"readOnly":false},"cache_result_ts":{"type":"integer","format":"int64","default":0,"readOnly":false}},"required":["cache_hit","count","precision","query_status"]}]},"Result":{"type":"object"},"QueryPrecisionMode":{"type":"string","enum":["FULL_PRECISION","MEDIUM_PRECISION","LOWER_PRECISION","defaultMode"],"readOnly":false},"SelectionResult":{"allOf":[{"$ref":"#/components/schemas/Result"},{"type":"object","properties":{"cache_hit":{"type":"boolean","default":false,"readOnly":false},"query_status":{"$ref":"#/components/schemas/OTQLRequestStatus"},"offset":{"type":"integer","format":"int64","default":0,"readOnly":false},"limit":{"type":"integer","format":"int32","default":0,"readOnly":false},"result":{"type":"string","readOnly":false},"count":{"type":"integer","format":"int64","default":0,"readOnly":false},"cache_result_ts":{"type":"integer","format":"int64","default":0,"readOnly":false},"took":{"type":"integer","format":"int64","default":0,"readOnly":false}},"required":["cache_hit","count","query_status","result"]}]},"NoResult":{"type":"object","properties":{"query_status":{"$ref":"#/components/schemas/OTQLRequestStatus"},"retryable":{"type":"boolean","default":false,"readOnly":false}},"required":["query_status"]},"AggregationResult":{"allOf":[{"$ref":"#/components/schemas/Result"},{"type":"object","properties":{"cache_result_ts":{"type":"integer","format":"int64","default":0,"readOnly":false},"query_status":{"$ref":"#/components/schemas/OTQLRequestStatus"},"count":{"type":"integer","format":"int64","default":0,"readOnly":false},"precision":{"$ref":"#/components/schemas/QueryPrecisionMode"},"aggregation":{"$ref":"#/components/schemas/OTQLAggregations"},"sampling_ratio":{"type":"number","format":"float","default":0,"readOnly":false},"took":{"type":"integer","format":"int64","default":0,"readOnly":false},"cache_hit":{"type":"boolean","default":false,"readOnly":false}},"required":["aggregation","cache_hit","count","precision","query_status"]}]},"OTQLAggregations":{"type":"object","properties":{"bucket_aggregations":{"type":"array","items":{"$ref":"#/components/schemas/OTQLBuckets"},"readOnly":false},"metric_aggregations":{"type":"array","items":{"$ref":"#/components/schemas/OTQLMetric"},"readOnly":false}},"required":["bucket_aggregations","metric_aggregations"]},"OTQLBuckets":{"type":"object","properties":{"name":{"type":"string","readOnly":false},"field_name":{"type":"string","readOnly":false},"bucket_type":{"type":"string","readOnly":false},"path":{"type":"string","readOnly":false},"buckets":{"type":"array","items":{"$ref":"#/components/schemas/OTQLBucket"},"readOnly":false},"type":{"type":"string","readOnly":false}},"required":["bucket_type","buckets","field_name","name","type"]},"OTQLBucket":{"type":"object","properties":{"key":{"type":"string","readOnly":false},"count":{"type":"integer","format":"int64","default":0,"readOnly":false},"aggregations":{"$ref":"#/components/schemas/OTQLAggregations"}},"required":["count","key"]},"OTQLMetric":{"discriminator":{"propertyName":"type","mapping":{"OTQL_SINGLE_METRIC":"#/components/schemas/OTQLSingleMetric","OTQL_AGGREGATION_METRIC":"#/components/schemas/OTQLMultipleMetric"}},"oneOf":[{"$ref":"#/components/schemas/OTQLSingleMetric"},{"$ref":"#/components/schemas/OTQLMultipleMetric"}],"properties":{"type":{"type":"string","enum":["OTQL_SINGLE_METRIC","OTQL_AGGREGATION_METRIC"]}},"required":["type"]},"OTQLSingleMetric":{"type":"object","properties":{"path":{"type":"string","readOnly":false},"name":{"type":"string","readOnly":false},"field_name":{"type":"string","readOnly":false},"metric_type":{"type":"string","readOnly":false},"value":{"type":"number","format":"float","default":0,"readOnly":false}},"required":["field_name","metric_type","name"]},"OTQLMultipleMetric":{"type":"object","properties":{"name":{"type":"string","readOnly":false},"path":{"type":"string","readOnly":false},"metric_type":{"type":"string","readOnly":false},"field_name":{"type":"string","readOnly":false},"value":{"type":"array","items":{"type":"number","format":"float","default":0,"readOnly":false},"readOnly":false}},"required":["field_name","metric_type","name","value"]},"errorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error_code":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTHORIZATION_ERROR","BAD_REQUEST_DATA","BAD_REQUEST_FORMAT","CONSTRAINT_VIOLATION_EXCEPTION","EMAIL_ALREADY_EXISTS","MAC_ERROR","RESOURCE_NOT_FOUND","SERVICE_UNAVAILABLE","TOKEN_ERROR"]},"error_id":{"type":"string"},"error":{"type":"string"}},"required":["error","error_code","error_id","status"]}},"responses":{"error":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorResponse"}}}}}}}
```

## GET /datamarts/{datamart\_id}/queries/{id}

> Get a query

```json
{"openapi":"3.1.1","info":{"title":"mediarithmics openapi API","version":"1.0.0"},"tags":[{"name":"Datamart queries","description":"Operations related to **OTQL Queries**, the query language for datamarts based on GraphQL. OTQL (Object Tree Query Language) enables querying user data across millions/billions of objects using a SELECT/FROM/WHERE pattern. Queries can be saved as objects for reuse in segments, exports, and other features with performance optimization through caching.\n\nRelevant documentation:\n- [OTQL queries](https://developer.mediarithmics.io/querying-your-data/otql-queries)\n- [OTQL examples](https://developer.mediarithmics.io/querying-your-data/otql-examples)\n"}],"servers":[{"url":"http://api.mediarithmics.local/v1","description":"Development server"},{"url":"https://api.mediarithmics.com/v1","description":"Production server"}],"paths":{"/datamarts/{datamart_id}/queries/{id}":{"get":{"tags":["Datamart queries"],"responses":{"200":{"description":"Success !","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"$ref":"#/components/schemas/QueryResource"}},"required":["data","status"]}}}},"400":{"$ref":"#/components/responses/error"},"401":{"$ref":"#/components/responses/error"},"403":{"$ref":"#/components/responses/error"},"404":{"$ref":"#/components/responses/error"},"500":{"$ref":"#/components/responses/error"},"503":{"$ref":"#/components/responses/error"}},"description":"","operationId":"getDatamartQueries","parameters":[{"explode":false,"schema":{"type":"integer","format":"int64"},"name":"datamart_id","in":"path","style":"simple","required":true},{"required":true,"schema":{"type":"integer","format":"int64"},"explode":false,"style":"simple","in":"path","name":"id"},{"required":false,"description":"Query language","style":"form","explode":true,"schema":{"$ref":"#/components/schemas/QueryLanguage"},"in":"query","name":"language"},{"name":"favorite","in":"query","required":false,"style":"form","schema":{"type":"boolean"},"description":"Query is favorite","explode":true}],"summary":"Get a query"}}},"components":{"schemas":{"QueryResource":{"type":"object","properties":{"datamart_id":{"type":"string","readOnly":true},"major_version":{"type":"integer","format":"int32","default":0,"readOnly":false},"query_language_subtype":{"$ref":"#/components/schemas/QueryLanguageSubtype"},"query_text":{"type":"string","readOnly":false},"favorite":{"type":"boolean","default":false,"readOnly":false},"minor_version":{"type":"integer","format":"int32","default":0,"readOnly":false},"query_language":{"$ref":"#/components/schemas/QueryLanguage"},"id":{"type":"string","readOnly":true}},"required":["datamart_id","favorite","id","major_version","minor_version","query_language","query_text"]},"QueryLanguageSubtype":{"type":"string","enum":["PARAMETRIC"],"readOnly":false},"QueryLanguage":{"type":"string","enum":["SELECTORQL","JSON_OTQL","OTQL","GRAPHQL","SQL"],"readOnly":false},"errorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error_code":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTHORIZATION_ERROR","BAD_REQUEST_DATA","BAD_REQUEST_FORMAT","CONSTRAINT_VIOLATION_EXCEPTION","EMAIL_ALREADY_EXISTS","MAC_ERROR","RESOURCE_NOT_FOUND","SERVICE_UNAVAILABLE","TOKEN_ERROR"]},"error_id":{"type":"string"},"error":{"type":"string"}},"required":["error","error_code","error_id","status"]}},"responses":{"error":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorResponse"}}}}}}}
```

## PUT /datamarts/{datamart\_id}/queries/{id}

> Update a query

```json
{"openapi":"3.1.1","info":{"title":"mediarithmics openapi API","version":"1.0.0"},"tags":[{"name":"Datamart queries","description":"Operations related to **OTQL Queries**, the query language for datamarts based on GraphQL. OTQL (Object Tree Query Language) enables querying user data across millions/billions of objects using a SELECT/FROM/WHERE pattern. Queries can be saved as objects for reuse in segments, exports, and other features with performance optimization through caching.\n\nRelevant documentation:\n- [OTQL queries](https://developer.mediarithmics.io/querying-your-data/otql-queries)\n- [OTQL examples](https://developer.mediarithmics.io/querying-your-data/otql-examples)\n"}],"servers":[{"url":"http://api.mediarithmics.local/v1","description":"Development server"},{"url":"https://api.mediarithmics.com/v1","description":"Production server"}],"paths":{"/datamarts/{datamart_id}/queries/{id}":{"put":{"description":"","responses":{"200":{"description":"Success !","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"$ref":"#/components/schemas/QueryResource"}},"required":["data","status"]}}}},"400":{"$ref":"#/components/responses/error"},"401":{"$ref":"#/components/responses/error"},"403":{"$ref":"#/components/responses/error"},"404":{"$ref":"#/components/responses/error"},"500":{"$ref":"#/components/responses/error"},"503":{"$ref":"#/components/responses/error"}},"summary":"Update a query","requestBody":{"description":"The query to update","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryResource"}}},"required":true},"operationId":"updateDatamartQuery","tags":["Datamart queries"],"parameters":[{"style":"simple","explode":false,"required":true,"in":"path","name":"datamart_id","schema":{"type":"integer","format":"int64"}},{"schema":{"type":"integer","format":"int64"},"explode":false,"name":"id","style":"simple","required":true,"in":"path"}]}}},"components":{"schemas":{"QueryResource":{"type":"object","properties":{"datamart_id":{"type":"string","readOnly":true},"major_version":{"type":"integer","format":"int32","default":0,"readOnly":false},"query_language_subtype":{"$ref":"#/components/schemas/QueryLanguageSubtype"},"query_text":{"type":"string","readOnly":false},"favorite":{"type":"boolean","default":false,"readOnly":false},"minor_version":{"type":"integer","format":"int32","default":0,"readOnly":false},"query_language":{"$ref":"#/components/schemas/QueryLanguage"},"id":{"type":"string","readOnly":true}},"required":["datamart_id","favorite","id","major_version","minor_version","query_language","query_text"]},"QueryLanguageSubtype":{"type":"string","enum":["PARAMETRIC"],"readOnly":false},"QueryLanguage":{"type":"string","enum":["SELECTORQL","JSON_OTQL","OTQL","GRAPHQL","SQL"],"readOnly":false},"errorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error_code":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTHORIZATION_ERROR","BAD_REQUEST_DATA","BAD_REQUEST_FORMAT","CONSTRAINT_VIOLATION_EXCEPTION","EMAIL_ALREADY_EXISTS","MAC_ERROR","RESOURCE_NOT_FOUND","SERVICE_UNAVAILABLE","TOKEN_ERROR"]},"error_id":{"type":"string"},"error":{"type":"string"}},"required":["error","error_code","error_id","status"]}},"responses":{"error":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorResponse"}}}}}}}
```

## DELETE /datamarts/{datamart\_id}/queries/{id}

> Delete a query

```json
{"openapi":"3.1.1","info":{"title":"mediarithmics openapi API","version":"1.0.0"},"tags":[{"name":"Datamart queries","description":"Operations related to **OTQL Queries**, the query language for datamarts based on GraphQL. OTQL (Object Tree Query Language) enables querying user data across millions/billions of objects using a SELECT/FROM/WHERE pattern. Queries can be saved as objects for reuse in segments, exports, and other features with performance optimization through caching.\n\nRelevant documentation:\n- [OTQL queries](https://developer.mediarithmics.io/querying-your-data/otql-queries)\n- [OTQL examples](https://developer.mediarithmics.io/querying-your-data/otql-examples)\n"}],"servers":[{"url":"http://api.mediarithmics.local/v1","description":"Development server"},{"url":"https://api.mediarithmics.com/v1","description":"Production server"}],"paths":{"/datamarts/{datamart_id}/queries/{id}":{"delete":{"summary":"Delete a query","parameters":[{"style":"simple","explode":false,"schema":{"type":"integer","format":"int64"},"in":"path","name":"datamart_id","required":true},{"name":"id","explode":false,"in":"path","schema":{"type":"integer","format":"int64"},"style":"simple","required":true}],"operationId":"deleteDatamartQuery","responses":{"200":{"$ref":"#/components/responses/simple"},"400":{"$ref":"#/components/responses/error"},"401":{"$ref":"#/components/responses/error"},"403":{"$ref":"#/components/responses/error"},"404":{"$ref":"#/components/responses/error"},"500":{"$ref":"#/components/responses/error"},"503":{"$ref":"#/components/responses/error"}},"description":"","tags":["Datamart queries"]}}},"components":{"responses":{"simple":{"description":"Success response","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]}},"required":["status"]}}}},"error":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorResponse"}}}}},"schemas":{"errorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error_code":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTHORIZATION_ERROR","BAD_REQUEST_DATA","BAD_REQUEST_FORMAT","CONSTRAINT_VIOLATION_EXCEPTION","EMAIL_ALREADY_EXISTS","MAC_ERROR","RESOURCE_NOT_FOUND","SERVICE_UNAVAILABLE","TOKEN_ERROR"]},"error_id":{"type":"string"},"error":{"type":"string"}},"required":["error","error_code","error_id","status"]}}}}
```

## POST /datamarts/{datamart\_id}/expression\_translations

> Translate a Json type expression to an output\_type expression

```json
{"openapi":"3.1.1","info":{"title":"mediarithmics openapi API","version":"1.0.0"},"tags":[{"name":"Datamart queries","description":"Operations related to **OTQL Queries**, the query language for datamarts based on GraphQL. OTQL (Object Tree Query Language) enables querying user data across millions/billions of objects using a SELECT/FROM/WHERE pattern. Queries can be saved as objects for reuse in segments, exports, and other features with performance optimization through caching.\n\nRelevant documentation:\n- [OTQL queries](https://developer.mediarithmics.io/querying-your-data/otql-queries)\n- [OTQL examples](https://developer.mediarithmics.io/querying-your-data/otql-examples)\n"}],"servers":[{"url":"http://api.mediarithmics.local/v1","description":"Development server"},{"url":"https://api.mediarithmics.com/v1","description":"Production server"}],"paths":{"/datamarts/{datamart_id}/expression_translations":{"post":{"responses":{"200":{"description":"Success !","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"$ref":"#/components/schemas/QueryTranslationResource"}},"required":["data","status"]}}}},"400":{"$ref":"#/components/responses/error"},"401":{"$ref":"#/components/responses/error"},"403":{"$ref":"#/components/responses/error"},"404":{"$ref":"#/components/responses/error"},"500":{"$ref":"#/components/responses/error"},"503":{"$ref":"#/components/responses/error"}},"parameters":[{"explode":false,"schema":{"type":"string"},"name":"datamart_id","style":"simple","in":"path","description":"Datamart id","required":true}],"summary":"Translate a Json type expression to an output_type expression","requestBody":{"description":"The expression to translate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryTranslationResource"}}},"required":true},"description":"","tags":["Datamart queries"],"operationId":"translateExpression"}}},"components":{"schemas":{"QueryTranslationResource":{"type":"object","properties":{"output_query_language_subtype":{"$ref":"#/components/schemas/QueryLanguageSubtype"},"input_query_language":{"$ref":"#/components/schemas/QueryLanguage"},"output_query_language":{"$ref":"#/components/schemas/QueryLanguage"},"output_query_text":{"type":"string","readOnly":true},"input_query_text":{"type":"string","readOnly":false},"input_query_language_subtype":{"$ref":"#/components/schemas/QueryLanguageSubtype"}},"required":["input_query_language","input_query_text","output_query_language","output_query_text"]},"QueryLanguageSubtype":{"type":"string","enum":["PARAMETRIC"],"readOnly":false},"QueryLanguage":{"type":"string","enum":["SELECTORQL","JSON_OTQL","OTQL","GRAPHQL","SQL"],"readOnly":false},"errorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error_code":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTHORIZATION_ERROR","BAD_REQUEST_DATA","BAD_REQUEST_FORMAT","CONSTRAINT_VIOLATION_EXCEPTION","EMAIL_ALREADY_EXISTS","MAC_ERROR","RESOURCE_NOT_FOUND","SERVICE_UNAVAILABLE","TOKEN_ERROR"]},"error_id":{"type":"string"},"error":{"type":"string"}},"required":["error","error_code","error_id","status"]}},"responses":{"error":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorResponse"}}}}}}}
```

## POST /datamarts/{datamart\_id}/query\_executions\_async/otql/{query\_id}/action

> Cancel a query

```json
{"openapi":"3.1.1","info":{"title":"mediarithmics openapi API","version":"1.0.0"},"tags":[{"name":"Datamart queries","description":"Operations related to **OTQL Queries**, the query language for datamarts based on GraphQL. OTQL (Object Tree Query Language) enables querying user data across millions/billions of objects using a SELECT/FROM/WHERE pattern. Queries can be saved as objects for reuse in segments, exports, and other features with performance optimization through caching.\n\nRelevant documentation:\n- [OTQL queries](https://developer.mediarithmics.io/querying-your-data/otql-queries)\n- [OTQL examples](https://developer.mediarithmics.io/querying-your-data/otql-examples)\n"}],"servers":[{"url":"http://api.mediarithmics.local/v1","description":"Development server"},{"url":"https://api.mediarithmics.com/v1","description":"Production server"}],"paths":{"/datamarts/{datamart_id}/query_executions_async/otql/{query_id}/action":{"post":{"responses":{"200":{"description":"Success !","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"$ref":"#/components/schemas/ObjectTreeQueryResultPublicResponse"}},"required":["data","status"]}}}},"400":{"$ref":"#/components/responses/error"},"401":{"$ref":"#/components/responses/error"},"403":{"$ref":"#/components/responses/error"},"404":{"$ref":"#/components/responses/error"},"500":{"$ref":"#/components/responses/error"},"503":{"$ref":"#/components/responses/error"}},"parameters":[{"description":"The datamart for which we register the query","in":"path","name":"datamart_id","schema":{"type":"string"},"style":"simple","explode":false,"required":true},{"name":"query_id","style":"simple","required":true,"schema":{"type":"string","format":"uuid"},"in":"path","explode":false}],"requestBody":{"description":"The query to register","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MakeObjectTreeQueryAction"}}},"required":true},"summary":"Cancel a query","description":"","tags":["Datamart queries"],"operationId":"asyncAction"}}},"components":{"schemas":{"ObjectTreeQueryResultPublicResponse":{"discriminator":{"propertyName":"type","mapping":{"NO_RESULT":"#/components/schemas/NoResult","COUNT_RESULT":"#/components/schemas/CountResult","ERROR_RESULT":"#/components/schemas/ErrorResult","AGGREGATION_RESULT":"#/components/schemas/AggregationResult","SELECTION_RESULT":"#/components/schemas/SelectionResult"}},"oneOf":[{"$ref":"#/components/schemas/ErrorResult"},{"$ref":"#/components/schemas/CountResult"},{"$ref":"#/components/schemas/SelectionResult"},{"$ref":"#/components/schemas/NoResult"},{"$ref":"#/components/schemas/AggregationResult"}],"properties":{"type":{"type":"string","enum":["ERROR_RESULT","COUNT_RESULT","SELECTION_RESULT","NO_RESULT","AGGREGATION_RESULT"]}},"required":["type"]},"ErrorResult":{"type":"object","properties":{"query_status":{"$ref":"#/components/schemas/OTQLRequestStatus"},"error":{"$ref":"#/components/schemas/OTQLPublicErrorTypes"},"retryable":{"type":"boolean","default":false,"readOnly":false}},"required":["error","query_status"]},"OTQLRequestStatus":{"type":"string","enum":["REGISTERED","PENDING","RUNNING","CANCELLED_BY_USER","CANCELLED_BY_PROXY","TIMEOUT","FAILED","SUCCESSFUL","LOST","publicRunning","publicCancelled","ended"],"readOnly":false},"OTQLPublicErrorTypes":{"type":"string","enum":["TREE_INDEX_ERROR","TIMEOUT","UPDATE_TO_RUNNING_EXCEPTION","UNDEFINED_ERROR","TOO_MANY_RESULTS","TIME_FRAME_TOO_WIDE"],"readOnly":false},"CountResult":{"allOf":[{"$ref":"#/components/schemas/Result"},{"type":"object","properties":{"took":{"type":"integer","format":"int64","default":0,"readOnly":false},"precision":{"$ref":"#/components/schemas/QueryPrecisionMode"},"query_status":{"$ref":"#/components/schemas/OTQLRequestStatus"},"cache_hit":{"type":"boolean","default":false,"readOnly":false},"sampling_ratio":{"type":"number","format":"float","default":0,"readOnly":false},"count":{"type":"integer","format":"int64","default":0,"readOnly":false},"cache_result_ts":{"type":"integer","format":"int64","default":0,"readOnly":false}},"required":["cache_hit","count","precision","query_status"]}]},"Result":{"type":"object"},"QueryPrecisionMode":{"type":"string","enum":["FULL_PRECISION","MEDIUM_PRECISION","LOWER_PRECISION","defaultMode"],"readOnly":false},"SelectionResult":{"allOf":[{"$ref":"#/components/schemas/Result"},{"type":"object","properties":{"cache_hit":{"type":"boolean","default":false,"readOnly":false},"query_status":{"$ref":"#/components/schemas/OTQLRequestStatus"},"offset":{"type":"integer","format":"int64","default":0,"readOnly":false},"limit":{"type":"integer","format":"int32","default":0,"readOnly":false},"result":{"type":"string","readOnly":false},"count":{"type":"integer","format":"int64","default":0,"readOnly":false},"cache_result_ts":{"type":"integer","format":"int64","default":0,"readOnly":false},"took":{"type":"integer","format":"int64","default":0,"readOnly":false}},"required":["cache_hit","count","query_status","result"]}]},"NoResult":{"type":"object","properties":{"query_status":{"$ref":"#/components/schemas/OTQLRequestStatus"},"retryable":{"type":"boolean","default":false,"readOnly":false}},"required":["query_status"]},"AggregationResult":{"allOf":[{"$ref":"#/components/schemas/Result"},{"type":"object","properties":{"cache_result_ts":{"type":"integer","format":"int64","default":0,"readOnly":false},"query_status":{"$ref":"#/components/schemas/OTQLRequestStatus"},"count":{"type":"integer","format":"int64","default":0,"readOnly":false},"precision":{"$ref":"#/components/schemas/QueryPrecisionMode"},"aggregation":{"$ref":"#/components/schemas/OTQLAggregations"},"sampling_ratio":{"type":"number","format":"float","default":0,"readOnly":false},"took":{"type":"integer","format":"int64","default":0,"readOnly":false},"cache_hit":{"type":"boolean","default":false,"readOnly":false}},"required":["aggregation","cache_hit","count","precision","query_status"]}]},"OTQLAggregations":{"type":"object","properties":{"bucket_aggregations":{"type":"array","items":{"$ref":"#/components/schemas/OTQLBuckets"},"readOnly":false},"metric_aggregations":{"type":"array","items":{"$ref":"#/components/schemas/OTQLMetric"},"readOnly":false}},"required":["bucket_aggregations","metric_aggregations"]},"OTQLBuckets":{"type":"object","properties":{"name":{"type":"string","readOnly":false},"field_name":{"type":"string","readOnly":false},"bucket_type":{"type":"string","readOnly":false},"path":{"type":"string","readOnly":false},"buckets":{"type":"array","items":{"$ref":"#/components/schemas/OTQLBucket"},"readOnly":false},"type":{"type":"string","readOnly":false}},"required":["bucket_type","buckets","field_name","name","type"]},"OTQLBucket":{"type":"object","properties":{"key":{"type":"string","readOnly":false},"count":{"type":"integer","format":"int64","default":0,"readOnly":false},"aggregations":{"$ref":"#/components/schemas/OTQLAggregations"}},"required":["count","key"]},"OTQLMetric":{"discriminator":{"propertyName":"type","mapping":{"OTQL_SINGLE_METRIC":"#/components/schemas/OTQLSingleMetric","OTQL_AGGREGATION_METRIC":"#/components/schemas/OTQLMultipleMetric"}},"oneOf":[{"$ref":"#/components/schemas/OTQLSingleMetric"},{"$ref":"#/components/schemas/OTQLMultipleMetric"}],"properties":{"type":{"type":"string","enum":["OTQL_SINGLE_METRIC","OTQL_AGGREGATION_METRIC"]}},"required":["type"]},"OTQLSingleMetric":{"type":"object","properties":{"path":{"type":"string","readOnly":false},"name":{"type":"string","readOnly":false},"field_name":{"type":"string","readOnly":false},"metric_type":{"type":"string","readOnly":false},"value":{"type":"number","format":"float","default":0,"readOnly":false}},"required":["field_name","metric_type","name"]},"OTQLMultipleMetric":{"type":"object","properties":{"name":{"type":"string","readOnly":false},"path":{"type":"string","readOnly":false},"metric_type":{"type":"string","readOnly":false},"field_name":{"type":"string","readOnly":false},"value":{"type":"array","items":{"type":"number","format":"float","default":0,"readOnly":false},"readOnly":false}},"required":["field_name","metric_type","name","value"]},"errorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error_code":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTHORIZATION_ERROR","BAD_REQUEST_DATA","BAD_REQUEST_FORMAT","CONSTRAINT_VIOLATION_EXCEPTION","EMAIL_ALREADY_EXISTS","MAC_ERROR","RESOURCE_NOT_FOUND","SERVICE_UNAVAILABLE","TOKEN_ERROR"]},"error_id":{"type":"string"},"error":{"type":"string"}},"required":["error","error_code","error_id","status"]},"MakeObjectTreeQueryAction":{"type":"object","properties":{"action":{"$ref":"#/components/schemas/ObjectTreeQueryAction"}},"required":["action"]},"ObjectTreeQueryAction":{"type":"string","enum":["CANCEL"],"readOnly":false}},"responses":{"error":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorResponse"}}}}}}}
```

## POST /datamarts/{datamart\_id}/query\_executions/jsonotql

> Execute a Json OTQL query

```json
{"openapi":"3.1.1","info":{"title":"mediarithmics openapi API","version":"1.0.0"},"tags":[{"name":"Datamart queries","description":"Operations related to **OTQL Queries**, the query language for datamarts based on GraphQL. OTQL (Object Tree Query Language) enables querying user data across millions/billions of objects using a SELECT/FROM/WHERE pattern. Queries can be saved as objects for reuse in segments, exports, and other features with performance optimization through caching.\n\nRelevant documentation:\n- [OTQL queries](https://developer.mediarithmics.io/querying-your-data/otql-queries)\n- [OTQL examples](https://developer.mediarithmics.io/querying-your-data/otql-examples)\n"}],"servers":[{"url":"http://api.mediarithmics.local/v1","description":"Development server"},{"url":"https://api.mediarithmics.com/v1","description":"Production server"}],"paths":{"/datamarts/{datamart_id}/query_executions/jsonotql":{"post":{"requestBody":{"description":"A raw query to execute if no queryId is provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryDocument"}}},"required":false},"tags":["Datamart queries"],"parameters":[{"explode":false,"name":"datamart_id","required":true,"style":"simple","in":"path","description":"The datamart for which we register the query","schema":{"type":"integer","format":"int64"}},{"name":"index_name","style":"form","required":false,"in":"query","schema":{"type":"string"},"description":"The tree index to use. Default to USER_INDEX","explode":true},{"style":"form","explode":true,"name":"queryId","required":false,"in":"query","description":"The id of the query to execute. If provided, the body will be ignored","schema":{"type":"string"}},{"required":false,"schema":{"type":"integer","format":"int32"},"description":"In case of select queries, the limit of returned elements","style":"form","explode":true,"in":"query","name":"limit"},{"schema":{"type":"integer","format":"int32"},"description":"In case of select queries, the offset of the first element","in":"query","explode":true,"style":"form","required":false,"name":"offset"},{"style":"form","name":"precision","in":"query","description":"Precision used to execute the query. Default to FULL_PRECISION","explode":true,"schema":{"$ref":"#/components/schemas/QueryPrecisionMode"},"required":false},{"name":"use_cache","schema":{"type":"boolean"},"in":"query","description":"Use the cache","style":"form","required":false,"explode":true},{"name":"X-Mics-Otql-Source","explode":false,"style":"simple","in":"header","required":false,"description":"Technical initiator","schema":{"type":"string"}}],"summary":"Execute a Json OTQL query","responses":{"200":{"description":"Success !","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"$ref":"#/components/schemas/OTQLResult"}},"required":["data","status"]}}}},"400":{"$ref":"#/components/responses/error"},"401":{"$ref":"#/components/responses/error"},"403":{"$ref":"#/components/responses/error"},"404":{"$ref":"#/components/responses/error"},"500":{"$ref":"#/components/responses/error"},"503":{"$ref":"#/components/responses/error"}},"description":"","operationId":"executeJsonOTQL"}}},"components":{"schemas":{"QueryDocument":{"type":"object","properties":{"operations":{"type":"array","items":{"$ref":"#/components/schemas/SelectionOperation"},"readOnly":false},"language_version":{"type":"string","readOnly":false},"from":{"type":"string","readOnly":false},"limit":{"type":"integer","format":"int32","default":0,"readOnly":false},"join":{"type":"array","items":{"$ref":"#/components/schemas/JoinNode"},"readOnly":false},"where":{"$ref":"#/components/schemas/ObjectTreeExpressionNode"}},"required":["from","join","language_version","operations"]},"SelectionOperation":{"type":"object","properties":{"selections":{"type":"array","items":{"$ref":"#/components/schemas/SelectionField"},"readOnly":false},"directives":{"type":"array","items":{"$ref":"#/components/schemas/DirectiveField"},"readOnly":false}},"required":["directives","selections"]},"SelectionField":{"type":"object","properties":{"name":{"type":"string","readOnly":false},"selections":{"type":"array","items":{"$ref":"#/components/schemas/SelectionField"},"readOnly":false},"directives":{"type":"array","items":{"$ref":"#/components/schemas/DirectiveField"},"readOnly":false},"alias":{"type":"string","readOnly":false}},"required":["directives","name","selections"]},"DirectiveField":{"type":"object","properties":{"name":{"type":"string","readOnly":false},"arguments":{"type":"array","items":{"$ref":"#/components/schemas/DirectiveArgument"},"readOnly":false}},"required":["arguments","name"]},"DirectiveArgument":{"type":"object","properties":{"name":{"type":"string","readOnly":false},"value":{"$ref":"#/components/schemas/Value"}},"required":["name","value"]},"Value":{"discriminator":{"propertyName":"type","mapping":{"NULL":"#/components/schemas/NullValue","BOOLEAN":"#/components/schemas/BooleanValue","LIST":"#/components/schemas/ListValue","ENUM":"#/components/schemas/EnumValue","UNDEFINED":"#/components/schemas/UndefinedValue","FLOAT":"#/components/schemas/FloatValue","PARAMETER":"#/components/schemas/ParameterValue","BIG_DECIMAL":"#/components/schemas/BigDecimalValue","INT":"#/components/schemas/IntValue","STRING":"#/components/schemas/StringValue","OBJECT":"#/components/schemas/ObjectValue","BIG_INT":"#/components/schemas/BigIntValue"}},"oneOf":[{"$ref":"#/components/schemas/EnumValue"},{"$ref":"#/components/schemas/BigIntValue"},{"$ref":"#/components/schemas/UndefinedValue"},{"$ref":"#/components/schemas/ParameterValue"},{"$ref":"#/components/schemas/FloatValue"},{"$ref":"#/components/schemas/IntValue"},{"$ref":"#/components/schemas/ListValue"},{"$ref":"#/components/schemas/ObjectValue"},{"$ref":"#/components/schemas/NullValue"},{"$ref":"#/components/schemas/StringValue"},{"$ref":"#/components/schemas/BigDecimalValue"},{"$ref":"#/components/schemas/BooleanValue"}],"properties":{"type":{"type":"string","enum":["ENUM","BIG_INT","UNDEFINED","PARAMETER","FLOAT","INT","LIST","OBJECT","NULL","STRING","BIG_DECIMAL","BOOLEAN"]}},"required":["type"]},"EnumValue":{"type":"object","properties":{"value":{"type":"string","readOnly":false}},"required":["value"]},"BigIntValue":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/BigInt"}},"required":["value"]},"BigInt":{"type":"integer"},"UndefinedValue":{"type":"object"},"ParameterValue":{"type":"object","properties":{"name":{"type":"string","readOnly":false}},"required":["name"]},"FloatValue":{"type":"object","properties":{"value":{"type":"number","format":"float","default":0,"readOnly":false}},"required":["value"]},"IntValue":{"type":"object","properties":{"value":{"type":"integer","format":"int32","default":0,"readOnly":false}},"required":["value"]},"ListValue":{"type":"object","properties":{"value":{"type":"array","items":{"$ref":"#/components/schemas/Value"},"readOnly":false}},"required":["value"]},"ObjectValue":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/ObjectField"},"readOnly":false}},"required":["fields"]},"ObjectField":{"type":"object","properties":{"name":{"type":"string","readOnly":false},"value":{"$ref":"#/components/schemas/Value"}},"required":["name","value"]},"NullValue":{"type":"object"},"StringValue":{"type":"object","properties":{"value":{"type":"string","readOnly":false}},"required":["value"]},"BigDecimalValue":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/BigDecimal"}},"required":["value"]},"BigDecimal":{"type":"number"},"BooleanValue":{"type":"object","properties":{"value":{"type":"boolean","default":false,"readOnly":false}},"required":["value"]},"JoinNode":{"type":"object","properties":{"from":{"type":"string","readOnly":false},"where":{"$ref":"#/components/schemas/ObjectTreeExpressionNode"}},"required":["from","where"]},"ObjectTreeExpressionNode":{"discriminator":{"propertyName":"type","mapping":{"GROUP":"#/components/schemas/GroupNode","OBJECT":"#/components/schemas/ObjectNode","PARAMETRIC_PREDICATE":"#/components/schemas/ParametricPredicateNode","FIELD":"#/components/schemas/FieldNode"}},"oneOf":[{"$ref":"#/components/schemas/GroupNode"},{"$ref":"#/components/schemas/ObjectNode"},{"$ref":"#/components/schemas/ParametricPredicateNode"},{"$ref":"#/components/schemas/FieldNode"}],"properties":{"type":{"type":"string","enum":["GROUP","OBJECT","PARAMETRIC_PREDICATE","FIELD"]}},"required":["type"]},"GroupNode":{"type":"object","properties":{"expressions":{"type":"array","items":{"$ref":"#/components/schemas/ObjectTreeExpressionNode"},"readOnly":false},"negation":{"type":"boolean","default":false,"readOnly":false},"boolean_operator":{"$ref":"#/components/schemas/QueryBooleanOperator"}},"required":["boolean_operator","expressions"]},"QueryBooleanOperator":{"type":"string","enum":["AND","OR"],"readOnly":false},"ObjectNode":{"type":"object","properties":{"min_score":{"type":"number","format":"float","default":0,"readOnly":false},"field":{"type":"string","readOnly":false},"directives":{"type":"array","items":{"$ref":"#/components/schemas/DirectiveField"},"readOnly":false},"expressions":{"type":"array","items":{"$ref":"#/components/schemas/ObjectTreeExpressionNode"},"readOnly":false},"score_field":{"type":"string","readOnly":false},"negation":{"type":"boolean","default":false,"readOnly":false},"score_function":{"$ref":"#/components/schemas/ObjectConditionAggregationFunction"},"boolean_operator":{"$ref":"#/components/schemas/QueryBooleanOperator"}},"required":["directives","expressions","field"]},"ObjectConditionAggregationFunction":{"type":"string","enum":["SUM","AVERAGE","MIN","MAX"],"readOnly":false},"ParametricPredicateNode":{"type":"object","properties":{"parametric_predicate_id":{"type":"string","readOnly":false},"parameters":{"type":"object","readOnly":false}},"required":["parameters","parametric_predicate_id"]},"FieldNode":{"type":"object","properties":{"field":{"type":"string","readOnly":false},"comparison":{"$ref":"#/components/schemas/QueryFieldComparison"},"existence":{"$ref":"#/components/schemas/QueryFieldExistence"}},"required":["field"]},"QueryFieldComparison":{"discriminator":{"propertyName":"type","mapping":{"BOOLEAN":"#/components/schemas/BooleanFieldComparison","STRING":"#/components/schemas/StringFieldComparison","NUMERIC":"#/components/schemas/NumericFieldComparison","ENUM":"#/components/schemas/EnumFieldComparison","TIME":"#/components/schemas/TimeFieldComparison","PARAMETRIC_VALUE":"#/components/schemas/ParametricValueComparison"}},"oneOf":[{"$ref":"#/components/schemas/EnumFieldComparison"},{"$ref":"#/components/schemas/NumericFieldComparison"},{"$ref":"#/components/schemas/ParametricValueComparison"},{"$ref":"#/components/schemas/StringFieldComparison"},{"$ref":"#/components/schemas/BooleanFieldComparison"},{"$ref":"#/components/schemas/TimeFieldComparison"}],"properties":{"type":{"type":"string","enum":["ENUM","NUMERIC","PARAMETRIC_VALUE","STRING","BOOLEAN","TIME"]}},"required":["type"]},"EnumFieldComparison":{"type":"object","properties":{"operator":{"$ref":"#/components/schemas/EnumComparisonOperator"},"values":{"type":"array","items":{"type":"string","readOnly":false},"readOnly":false}},"required":["operator","values"]},"EnumComparisonOperator":{"type":"string","enum":["EQUAL","NOT_EQUAL"],"readOnly":false},"NumericFieldComparison":{"type":"object","properties":{"operator":{"$ref":"#/components/schemas/NumericComparisonOperator"},"values":{"type":"array","items":{"type":"number","format":"float","default":0,"readOnly":false},"readOnly":false}},"required":["operator","values"]},"NumericComparisonOperator":{"type":"string","enum":["EQUAL","NOT_EQUAL","LT","LTE","GT","GTE"],"readOnly":false},"ParametricValueComparison":{"type":"object","properties":{"operator":{"$ref":"#/components/schemas/ParametricValueComparisonOperator"},"parameter_name":{"type":"string","readOnly":false}},"required":["operator","parameter_name"]},"ParametricValueComparisonOperator":{"type":"string","enum":["EQ","NOT_EQ","LT","LTE","GT","GTE","MATCHES","MATCHES_ALL","STARTS_WITH","IN"],"readOnly":false},"StringFieldComparison":{"type":"object","properties":{"operator":{"$ref":"#/components/schemas/StringComparisonOperator"},"values":{"type":"array","items":{"type":"string","readOnly":false},"readOnly":false}},"required":["operator","values"]},"StringComparisonOperator":{"type":"string","enum":["EQ","NOT_EQ","MATCHES","MATCHES_ALL","DOES_NOT_MATCH","STARTS_WITH","DOES_NOT_START_WITH"],"readOnly":false},"BooleanFieldComparison":{"type":"object","properties":{"operator":{"$ref":"#/components/schemas/BooleanComparisonOperator"},"values":{"type":"array","items":{"type":"boolean","default":false,"readOnly":false},"readOnly":false}},"required":["operator","values"]},"BooleanComparisonOperator":{"type":"string","enum":["EQUAL","NOT_EQUAL"],"readOnly":false},"TimeFieldComparison":{"type":"object","properties":{"operator":{"$ref":"#/components/schemas/TimeComparisonOperator"},"values":{"type":"array","items":{"type":"string","readOnly":false},"readOnly":false}},"required":["operator","values"]},"TimeComparisonOperator":{"type":"string","enum":["BEFORE","BEFORE_OR_EQUAL","AFTER","AFTER_OR_EQUAL","EQ"],"readOnly":false},"QueryFieldExistence":{"type":"string","enum":["EXISTS","DOES_NOT_EXIST"],"readOnly":false},"QueryPrecisionMode":{"type":"string","enum":["FULL_PRECISION","MEDIUM_PRECISION","LOWER_PRECISION","defaultMode"],"readOnly":false},"OTQLResult":{"type":"object","properties":{"warning_message":{"type":"string","readOnly":false},"took":{"type":"integer","format":"int32","default":0,"readOnly":false},"limit":{"type":"integer","format":"int32","default":0,"readOnly":false},"cache_result_ts":{"type":"integer","format":"int64","default":0,"readOnly":false},"offset":{"type":"integer","format":"int32","default":0,"readOnly":false},"result_type":{"$ref":"#/components/schemas/OTQLResultType"},"rows":{"type":"string","readOnly":false},"precision":{"$ref":"#/components/schemas/QueryPrecisionMode"},"sampling_ratio":{"type":"number","format":"float","default":0,"readOnly":false},"cache_hit":{"type":"boolean","default":false,"readOnly":false},"timed_out":{"type":"boolean","default":false,"readOnly":false}},"required":["precision","result_type","rows"]},"OTQLResultType":{"type":"string","enum":["COUNT","AGGREGATION","SELECTION"],"readOnly":false},"errorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error_code":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTHORIZATION_ERROR","BAD_REQUEST_DATA","BAD_REQUEST_FORMAT","CONSTRAINT_VIOLATION_EXCEPTION","EMAIL_ALREADY_EXISTS","MAC_ERROR","RESOURCE_NOT_FOUND","SERVICE_UNAVAILABLE","TOKEN_ERROR"]},"error_id":{"type":"string"},"error":{"type":"string"}},"required":["error","error_code","error_id","status"]}},"responses":{"error":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorResponse"}}}}}}}
```

## GET /datamarts/{datamart\_id}/queries

> Search document queries

```json
{"openapi":"3.1.1","info":{"title":"mediarithmics openapi API","version":"1.0.0"},"tags":[{"name":"Mediarithmics most used API","description":"These operations where flagged by mediarithmics teams as most useful."},{"name":"Datamart queries","description":"Operations related to **OTQL Queries**, the query language for datamarts based on GraphQL. OTQL (Object Tree Query Language) enables querying user data across millions/billions of objects using a SELECT/FROM/WHERE pattern. Queries can be saved as objects for reuse in segments, exports, and other features with performance optimization through caching.\n\nRelevant documentation:\n- [OTQL queries](https://developer.mediarithmics.io/querying-your-data/otql-queries)\n- [OTQL examples](https://developer.mediarithmics.io/querying-your-data/otql-examples)\n"}],"servers":[{"url":"http://api.mediarithmics.local/v1","description":"Development server"},{"url":"https://api.mediarithmics.com/v1","description":"Production server"}],"paths":{"/datamarts/{datamart_id}/queries":{"get":{"tags":["Datamart queries","Mediarithmics most used API"],"responses":{"200":{"description":"Success !","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer"},"first_result":{"type":"integer"},"status":{"type":"string","enum":["ok"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/QueryResource"}},"max_results":{"type":"integer"},"count":{"type":"integer"}},"required":["count","data","first_result","max_results","status","total"]}}}},"400":{"$ref":"#/components/responses/error"},"401":{"$ref":"#/components/responses/error"},"403":{"$ref":"#/components/responses/error"},"404":{"$ref":"#/components/responses/error"},"500":{"$ref":"#/components/responses/error"},"503":{"$ref":"#/components/responses/error"}},"operationId":"findDatamartQueries","summary":"Search document queries","parameters":[{"explode":false,"in":"path","schema":{"type":"integer","format":"int64"},"style":"simple","name":"datamart_id","required":true},{"in":"query","style":"form","explode":true,"schema":{"$ref":"#/components/schemas/QueryLanguage"},"name":"query_language","required":false,"description":"Query language"},{"in":"query","name":"query_language_subtype","description":"Query language subtype","explode":true,"style":"form","required":false,"schema":{"$ref":"#/components/schemas/QueryLanguageSubtype"}},{"in":"query","description":"Query is favorite","required":false,"name":"favorite","style":"form","explode":true,"schema":{"type":"boolean"}}],"description":""}}},"components":{"schemas":{"QueryResource":{"type":"object","properties":{"datamart_id":{"type":"string","readOnly":true},"major_version":{"type":"integer","format":"int32","default":0,"readOnly":false},"query_language_subtype":{"$ref":"#/components/schemas/QueryLanguageSubtype"},"query_text":{"type":"string","readOnly":false},"favorite":{"type":"boolean","default":false,"readOnly":false},"minor_version":{"type":"integer","format":"int32","default":0,"readOnly":false},"query_language":{"$ref":"#/components/schemas/QueryLanguage"},"id":{"type":"string","readOnly":true}},"required":["datamart_id","favorite","id","major_version","minor_version","query_language","query_text"]},"QueryLanguageSubtype":{"type":"string","enum":["PARAMETRIC"],"readOnly":false},"QueryLanguage":{"type":"string","enum":["SELECTORQL","JSON_OTQL","OTQL","GRAPHQL","SQL"],"readOnly":false},"errorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error_code":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTHORIZATION_ERROR","BAD_REQUEST_DATA","BAD_REQUEST_FORMAT","CONSTRAINT_VIOLATION_EXCEPTION","EMAIL_ALREADY_EXISTS","MAC_ERROR","RESOURCE_NOT_FOUND","SERVICE_UNAVAILABLE","TOKEN_ERROR"]},"error_id":{"type":"string"},"error":{"type":"string"}},"required":["error","error_code","error_id","status"]}},"responses":{"error":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorResponse"}}}}}}}
```

## POST /datamarts/{datamart\_id}/queries

> Create a query

```json
{"openapi":"3.1.1","info":{"title":"mediarithmics openapi API","version":"1.0.0"},"tags":[{"name":"Mediarithmics most used API","description":"These operations where flagged by mediarithmics teams as most useful."},{"name":"Datamart queries","description":"Operations related to **OTQL Queries**, the query language for datamarts based on GraphQL. OTQL (Object Tree Query Language) enables querying user data across millions/billions of objects using a SELECT/FROM/WHERE pattern. Queries can be saved as objects for reuse in segments, exports, and other features with performance optimization through caching.\n\nRelevant documentation:\n- [OTQL queries](https://developer.mediarithmics.io/querying-your-data/otql-queries)\n- [OTQL examples](https://developer.mediarithmics.io/querying-your-data/otql-examples)\n"}],"servers":[{"url":"http://api.mediarithmics.local/v1","description":"Development server"},{"url":"https://api.mediarithmics.com/v1","description":"Production server"}],"paths":{"/datamarts/{datamart_id}/queries":{"post":{"parameters":[{"name":"datamart_id","required":true,"style":"simple","explode":false,"in":"path","schema":{"type":"integer","format":"int64"}}],"requestBody":{"description":"The query to create","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryResource"}}},"required":true},"responses":{"200":{"description":"Success !","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"$ref":"#/components/schemas/QueryResource"}},"required":["data","status"]}}}},"400":{"$ref":"#/components/responses/error"},"401":{"$ref":"#/components/responses/error"},"403":{"$ref":"#/components/responses/error"},"404":{"$ref":"#/components/responses/error"},"500":{"$ref":"#/components/responses/error"},"503":{"$ref":"#/components/responses/error"}},"tags":["Datamart queries","Mediarithmics most used API"],"description":"","operationId":"createDatamartQuery","summary":"Create a query"}}},"components":{"schemas":{"QueryResource":{"type":"object","properties":{"datamart_id":{"type":"string","readOnly":true},"major_version":{"type":"integer","format":"int32","default":0,"readOnly":false},"query_language_subtype":{"$ref":"#/components/schemas/QueryLanguageSubtype"},"query_text":{"type":"string","readOnly":false},"favorite":{"type":"boolean","default":false,"readOnly":false},"minor_version":{"type":"integer","format":"int32","default":0,"readOnly":false},"query_language":{"$ref":"#/components/schemas/QueryLanguage"},"id":{"type":"string","readOnly":true}},"required":["datamart_id","favorite","id","major_version","minor_version","query_language","query_text"]},"QueryLanguageSubtype":{"type":"string","enum":["PARAMETRIC"],"readOnly":false},"QueryLanguage":{"type":"string","enum":["SELECTORQL","JSON_OTQL","OTQL","GRAPHQL","SQL"],"readOnly":false},"errorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error_code":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTHORIZATION_ERROR","BAD_REQUEST_DATA","BAD_REQUEST_FORMAT","CONSTRAINT_VIOLATION_EXCEPTION","EMAIL_ALREADY_EXISTS","MAC_ERROR","RESOURCE_NOT_FOUND","SERVICE_UNAVAILABLE","TOKEN_ERROR"]},"error_id":{"type":"string"},"error":{"type":"string"}},"required":["error","error_code","error_id","status"]}},"responses":{"error":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorResponse"}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.mediarithmics.io/api-reference/datamart-operations/datamart-queries.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.