> ## Documentation Index
> Fetch the complete documentation index at: https://docs.file.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Execute a query builder configuration
> Executes a query builder configuration using the workspace and organization bound to the API key.
Run a query builder configuration against your extracted document data and get
tabular rows back. The workspace and organization are taken from the API key, so
the configuration itself carries no tenancy.
## Use Cases
Pull aggregated figures across document types for dashboards and reports
Join related documents (for example purchase orders and invoices) and compare fields
Select and order specific fields for downstream systems
Filter for documents that fail a business rule
## Request Parameters
### Request Body
| Property | Type | Required | Description |
| ----------- | ------ | -------- | ----------------------------------------------- |
| queryConfig | object | Yes | The query builder configuration |
| options | object | No | Execution settings such as `limit` and `offset` |
#### queryConfig
All properties are optional; combine the ones your query needs.
| Property | Type | Description |
| ------------------- | ------ | ------------------------------------------------------------------- |
| documentTypes | array | Document type (file type) ids to query over |
| foldersContext | array | Directory ids to scope the query to |
| filters | array | Filter conditions applied to the selected documents |
| filterGroups | array | Grouped filter conditions for nested AND/OR logic |
| selectedFields | array | Fields to return, each with its alias |
| aggregations | array | Aggregations (for example count, sum, average) to compute |
| joins | array | Joins between document types |
| orderBy | array | Ordering clauses |
| virtualColumns | array | Computed columns derived from other fields |
| queryConfigs | array | Chained sub-configurations, each with an `id` and a nested `config` |
| directoryValidation | object | Directory-level validation configuration |
| headerOrder | array | Explicit ordering of the returned headers |
#### options
| Property | Type | Description |
| ------------- | ------- | ------------------------------------------------- |
| limit | number | Maximum number of rows to return |
| offset | number | Number of rows to skip |
| fieldMetadata | object | Field metadata passed through to execution |
| skipCache | boolean | Bypass cached results and execute the query fresh |
`queryConfig` mirrors the query builder in the fileAI app. The most reliable
way to author one is to build the query in the UI and reuse its configuration
here.
## Response
| Field | Type | Description |
| --------------- | ------ | ----------------------------------------------------------- |
| data | array | Rows returned by the query |
| headers | object | Header metadata keyed by the selected field aliases |
| rowCount | number | Number of rows returned |
| executionTimeMs | number | Server-side execution time in milliseconds |
| errors | array | Validation errors, present when the query config is invalid |
A `200` response can still carry `errors` when the query configuration is
invalid. Check `errors` before treating `data` as complete.
## Idempotency
`Idempotency-Key` is accepted for client uniformity but **ignored** here: the
endpoint has no side effects, and a retry can legitimately return different
rows, so replaying a cached response would hand back stale data. See
[Idempotent requests](/docs-api/api-idempotency).
## OpenAPI
````yaml post /prod/v1/query/execute
openapi: 3.0.0
info:
title: Public API
description: >-
### Welcome to fileAI’s Public API Documentation.
This API allows users to check the health of the system, upload and manage
files, and manage AI Schemas.
Should you have any questions, please reach out to fileAI via the “Contact a
Developer” link below.
[Contact a Developer](mailto:support@file.ai)
### Prerequisites
Before using our API, please ensure you complete the following prerequisites
- You must have a fileAI account. Sign up or login
[here](https://orion.file.ai/en/sign-up)
- You must have an API Key. After creating your fileAI account, you can
generate your API Key. Refer to the Authentication section below for more
details.
### Authentication
All API requests require an API key for authentication.
- To obtain your API key, please log in to your fileAI account and navigate
to Project Settings in your dashboard
- Keep your API key secure and do not share it publicly.
### How to Use Your API Key
Once you have your API key:
- Click the Authorize button on the top-right of this page
- Enter your API Key under Value
- Click Authorize to start making authenticated requests directly from the
documentation
version: '1.0'
contact: {}
servers:
- url: https://api.orion.file.ai
description: Default. Use this unless your workspace is on an instance.
- url: https://api.orion.{instance}.file.ai
description: Instance-specific host.
variables:
instance:
default: au
enum:
- au
- sg
- jp
description: >-
Instance hosting your workspace: au (Australia), sg (Singapore), jp
(Japan).
security: []
tags:
- name: Public API V1
paths:
/prod/v1/query/execute:
post:
tags:
- Public API V1
summary: Execute a query builder configuration
description: >-
Executes a query builder configuration using the workspace and
organization bound to the API key.
operationId: PublicAPIController_executeQuery
parameters:
- name: Idempotency-Key
in: header
description: >-
Accepted for client uniformity but IGNORED on this endpoint. It has
no side effects, and a retry can legitimately return different
results, so replaying a cached response would hand back stale data.
Every request executes fresh: no 24h window, no replay, no
Idempotent-Replayed header, and no key-reuse 422.
required: false
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ExecuteQueryForPAInput'
responses:
'200':
description: Query executed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ExecuteQueryForPAOutput'
'401':
description: Missing or invalid API key.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
'403':
description: Read-only or inactive API key.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
'404':
description: Resource not found.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
'422':
description: Validation failed.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
'429':
description: Rate limit exceeded.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
'500':
description: Unexpected internal error.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
security:
- x-api-key: []
components:
schemas:
ExecuteQueryForPAInput:
type: object
properties:
queryConfig:
description: Query builder configuration payload
allOf:
- $ref: '#/components/schemas/QueryConfigInput'
options:
description: Optional execution settings such as limit and offset
allOf:
- $ref: '#/components/schemas/QueryExecutionOptionsInput'
required:
- queryConfig
ExecuteQueryForPAOutput:
type: object
properties:
data:
description: Rows returned by the query
type: array
items:
type: object
headers:
type: object
description: Headers metadata keyed by selected field aliases
executionTimeMs:
type: number
description: Execution time in milliseconds
rowCount:
type: number
description: Number of rows returned
errors:
description: Validation errors when query config is invalid
type: array
items:
type: object
required:
- data
- headers
- executionTimeMs
- rowCount
ProblemDetailsDto:
type: object
properties:
type:
type: string
description: A URI identifying the problem type.
example: https://errors.file.ai/validation-failed
title:
type: string
description: Stable, human-readable summary of the problem type.
example: Validation failed
status:
type: number
description: HTTP status code.
example: 422
detail:
type: string
description: Human-readable explanation specific to this occurrence.
example: One or more fields are invalid.
instance:
type: string
description: URI reference for this occurrence (the request path).
example: /v1/files/upload
code:
type: string
description: Stable machine-readable error code.
example: VALIDATION_FAILED
requestId:
type: string
description: Correlation id for this request.
example: 0f1c8e03-978e-40d5-bc93-6894a57f9324
errors:
description: Field-level violations (validation only).
type: array
items:
$ref: '#/components/schemas/ProblemErrorItemDto'
retryAfter:
type: number
description: Seconds until the client may retry (present on 429 only).
example: 42
message:
type: string
description: Legacy key (deprecated — use `detail`/`title`).
example: Validation failed
error:
type: string
description: Legacy key (deprecated — use `title`).
example: Unprocessable Entity
statusCode:
type: number
description: Legacy key (deprecated — use `status`).
example: 422
required:
- type
- title
- status
- detail
- instance
- code
- requestId
- errors
- message
- error
- statusCode
QueryConfigInput:
type: object
properties: {}
QueryExecutionOptionsInput:
type: object
properties: {}
ProblemErrorItemDto:
type: object
properties:
code:
type: string
example: REQUIRED
detail:
type: string
example: must not be empty
pointer:
type: string
description: JSON Pointer to the offending body field.
example: '#/fileName'
parameter:
type: string
description: Name of the offending query/header parameter.
example: limit
required:
- code
- detail
securitySchemes:
x-api-key:
type: apiKey
in: header
name: x-api-key
description: API key for authentication
````