> ## Documentation Index > Fetch the complete documentation index at: https://developers.askparable.com/llms.txt > Use this file to discover all available pages before exploring further. # Query the Provider Pool > Runs one SQL statement over the Provider Pools (providers, providers_quarantine, providers_quality) and returns a view a model can read. 1. sql is one read-only statement. 2. parameters bind $1, $2 in order; identifiers cannot be bound. 3. The view holds whole leading rows within 60,000 characters, columns included, and cuts a text or binary value at 2,000; truncated says which limit applied and warnings say what to change. 4. returnedRows counts the rows shown, never the total. 5. A 64-bit integer past 2^53 and every decimal arrive as text beside their arrowType. 6. A table in another Pool is an unknown relation (QL-PL-002). ## Access An MCP token or a Parable token can call this operation. See [Authentication](https://developers.askparable.com/getting-started/authentication.md) for the kinds of token. Your roles must grant `tenant.data.query.providers`. ## Errors * `HTTP 400`: Parable refused the SQL. The message gives the reason, and the code is a QL code, such as QL-PL-002 for a table or function the Provider Pools do not serve. Correct the SQL from the stated reason; describe the table again if a name is unknown. Do not resend the same statement. * `HTTP 403`: The caller may not query data in this Workspace. Ask a Workspace Administrator for the Provider Pools Reader role. A different query does not help. * `HTTP 504`: The statement ran past its time budget (a QL-TO code) or did not finish in 30 seconds. Filter on a partition column, aggregate, or add a LIMIT. * `HTTP 429`: Too many queries were running, so the statement did not start (QL-IN-008), or the caller sent more than 120 of these requests in a minute. Nothing ran. Wait a moment, or for the seconds in the Retry-After header when it is set, then send the same request again. * `HTTP 503`: The statement stopped for lack of memory (QL-IN-009), or a service it needs did not answer, such as the model service behind semantic ranking or a SQL AI function (QL-IN-010). The code says which. Try again shortly. For QL-IN-009, read fewer columns or rows, or aggregate. ## OpenAPI ````yaml /api-reference/openapi.json post /api/provider-pool/query openapi: 3.0.3 info: description: >- Use the Workspace API to work with artifacts, connectors, Parables, and account resources. title: Workspace API version: v2026.10.22.1 servers: [] security: [] paths: /api/provider-pool/query: post: tags: - Provider pool summary: Query the Provider Pool description: >- Runs one SQL statement over the Provider Pools (providers, providers_quarantine, providers_quality) and returns a view a model can read. 1. sql is one read-only statement. 2. parameters bind $1, $2 in order; identifiers cannot be bound. 3. The view holds whole leading rows within 60,000 characters, columns included, and cuts a text or binary value at 2,000; truncated says which limit applied and warnings say what to change. 4. returnedRows counts the rows shown, never the total. 5. A 64-bit integer past 2^53 and every decimal arrive as text beside their arrowType. 6. A table in another Pool is an unknown relation (QL-PL-002). operationId: ProviderPoolQueryProviderPoolHandler parameters: - description: >- Workspace slug. Overrides subdomain-based workspace resolution when provided. in: header name: X-Tenant required: false schema: example: acme type: string - description: Optional request correlation ID echoed back in the response. in: header name: X-Request-ID required: false schema: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/ProviderPoolQueryInput' required: true responses: '200': content: application/json: schema: properties: data: $ref: '#/components/schemas/QueryResultView' links: $ref: '#/components/schemas/ResponseLinks' meta: $ref: '#/components/schemas/ResponseMeta' required: - data - meta type: object description: Successful response headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' '400': content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' description: >- The request is not valid. `detail` says why. A value that breaks a field rule gives the code `WA-VL-001` and an `errors` member that names each field. headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' '401': content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' description: The token is missing, malformed, revoked, or expired. headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' '403': content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' description: >- The token cannot make this request. For example, the roles of its owner do not allow the operation. headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' '413': content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' description: The request body is larger than 1 MB. headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' '429': content: text/plain: schema: example: Too Many Requests type: string description: >- More than 120 requests a minute came from your address. Wait for the number of seconds in `Retry-After`, then try again. headers: Retry-After: description: The number of seconds to wait before you try again. schema: type: integer X-Request-ID: $ref: '#/components/headers/X-Request-ID' '500': content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' description: The request failed on the server. headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' '504': content: text/plain: schema: example: Gateway Timeout type: string description: The operation did not finish in 30 seconds. headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' security: - bearerAuth: [] x-codeSamples: - label: TypeScript SDK lang: typescript source: >- import { WebApiSDK } from "@parable-platform/web-api-sdk"; import type { ProviderPoolQueryInput } from "@parable-platform/web-api-types"; const sdk = new WebApiSDK({ baseUrl: process.env.PARABLE_API_URL!, auth: { token: process.env.PARABLE_API_TOKEN! }, requestInterceptor: (config) => ({ ...config, headers: { ...config.headers, "X-Tenant": process.env.PARABLE_WORKSPACE! }, }), }); const input: ProviderPoolQueryInput = JSON.parse(`{ "sql": "example" }`); const result = await sdk.providerPool.queryProviderPool( input ); - label: Python SDK lang: python source: |- import json import os from parable_types_web_api import ProviderPoolQueryInput from parable_web_api_sdk import ClientConfig, WebApiSDK sdk = WebApiSDK( ClientConfig( base_url=os.environ["PARABLE_API_URL"], auth_token=os.environ["PARABLE_API_TOKEN"], default_headers={"X-Tenant": os.environ["PARABLE_WORKSPACE"]}, ) ) input_data = ProviderPoolQueryInput.model_validate( json.loads("{\"sql\":\"example\"}"), ) result = sdk.provider_pool.query_provider_pool(input_data) - label: Rust SDK lang: rust source: >- use parable_web_api_sdk::{types, ClientConfig, RequestOptions, WebApiSdk}; let sdk = WebApiSdk::new(ClientConfig::with_base_url( std::env::var("PARABLE_API_URL")?, Some(std::env::var("PARABLE_API_TOKEN")?), None, ))?; let options = RequestOptions::with_header("X-Tenant", std::env::var("PARABLE_WORKSPACE")?, None, None); let input: types::ProviderPoolQueryInput = serde_json::from_value( serde_json::json!({ "sql": "example" }), )?; let result = sdk.provider_pool.query_provider_pool( input, Some(&options) ).await?; - label: Go SDK lang: go source: "sdk, err := webapisdk.New(webapisdk.SDKConfig{\n\tBaseURL: os.Getenv(\"PARABLE_API_URL\"),\n\tAuth: &webapisdk.AuthConfig{Token: os.Getenv(\"PARABLE_API_TOKEN\")},\n\tRequestInterceptor: func(ctx context.Context, req *http.Request) error {\n\t\treq.Header.Set(\"X-Tenant\", os.Getenv(\"PARABLE_WORKSPACE\"))\n\t\treturn nil\n\t},\n})\nif err != nil {\n\treturn err\n}\n\nvar input webapitypes.ProviderPoolQueryInput\nif err := json.Unmarshal([]byte(`{\"sql\":\"example\"}`), &input); err != nil {\n\treturn err\n}\nresult, err := sdk.ProviderPoolNamespace.QueryProviderPool(ctx, input)" components: schemas: ProviderPoolQueryInput: description: |- One SQL statement to run against the Provider Pools, or to plan without running. properties: parameters: description: >- Positional values for $1, $2, ... placeholders, sent through Flight SQL prepared-statement binding. Values are never interpolated into SQL. Each value is a JSON scalar (string, finite number, boolean, or null). Identifiers and the arguments of search_available_data cannot be bound. items: description: 'Any valid JSON value: object, array, primitive, or null' nullable: true type: array sql: description: >- Single read-only SQL statement. Text.Sql rejects empty; maxLength is 100000 bytes. maxLength: 100000 minLength: 1 pattern: ^[\s\S]*$ type: string required: - sql type: object QueryResultView: description: >- A SQL result a model can read: typed columns and whole leading rows as JSON. Each row is a JSON array with one value per column, in column order. A value is written by its column's arrowType: 1. A 64-bit integer inside the JavaScript safe range, a smaller integer and a finite float are JSON numbers. A 64-bit integer past 2^53 - 1 is text. 2. A decimal is text with every digit of its scale, such as `1.50`. 3. A date is `YYYY-MM-DD`. A timestamp is ISO 8601 with the fraction its unit holds; one with a time zone is the UTC instant and ends with `Z`, one without is a wall-clock time and carries no zone. 4. A time is `HH:MM:SS` with its fraction, a duration ISO 8601 seconds. 5. Binary is base64. A struct is an object, a list an array, a map an object. 6. A null is JSON null. Nothing is rounded. properties: catalogVersion: description: >- The catalog the statement was planned against. Null when Parable does not report one with a result. nullable: true type: string columns: items: $ref: '#/components/schemas/QueryResultColumn' type: array elapsedMs: description: >- Signed integer count of milliseconds: an amount of elapsed time, never a point in time. An epoch timestamp is Temporal.DateTime with x-temporal-format: unix_millis. format: int64 maximum: 9007199254740991 minimum: -9007199254740991 type: integer requestId: description: The request's id in the Workspace API's logs. type: string returnedRows: description: The rows in this view. It is never the statement's total. format: int64 maximum: 9007199254740991 minimum: -9007199254740991 type: integer rows: items: description: 'Any valid JSON value: object, array, primitive, or null' type: array truncated: $ref: '#/components/schemas/QueryResultTruncation' warnings: description: What to change to see what was left out, in plain sentences. items: type: string type: array required: - columns - rows - returnedRows - truncated - elapsedMs - requestId - warnings type: object ResponseLinks: properties: first: nullable: true type: string last: nullable: true type: string next: nullable: true type: string prev: nullable: true type: string type: object ResponseMeta: properties: requestId: description: Unique identifier for the request type: string totalCount: description: Total count of items for paginated responses nullable: true type: integer required: - requestId type: object ProblemDetails: description: An error response in the Problem Details format (RFC 9457). properties: code: description: The stable error code, when the problem has one. example: WA-VL-001 type: string detail: description: What went wrong with this request. type: string details: description: >- Structured facts about the refusal, such as the entity or the path it concerns. Only some refusals have it. errors: description: >- The fields or filters that failed validation. Only a validation or filter error has it. requestId: description: >- The ID of the request, when the problem has one. The `X-Request-ID` response header always has it. type: string status: description: The HTTP status code. example: 400 type: integer title: description: A short summary, usually the text of the HTTP status. example: Bad Request type: string type: description: >- The problem type. It is `about:blank`: the status and `code` identify the problem. example: about:blank type: string required: - type - title - status - detail type: object QueryResultColumn: description: One column of a result or of a planned statement. properties: arrowType: description: >- The column's Arrow type, such as `int64`, `utf8`, `decimal(38, 9)` or `timestamp[us, tz=UTC]`. It says how to read a value that arrives as text. type: string name: type: string scalarRef: description: >- The Parable scalar the column carries, such as `Contact.Email`; null when it carries none. maxLength: 128 minLength: 3 nullable: true pattern: ^[A-Z][A-Za-z0-9]*\.[A-Z][A-Za-z0-9]*$ type: string required: - name - arrowType type: object QueryResultTruncation: description: |- What a result view left out. A view with any flag set is not the whole result. properties: capture: description: >- Reading stopped at 3 MiB of Arrow, so the statement may hold more rows than were read. type: boolean rows: description: >- Rows after the last one shown were left out to keep the view inside its 60,000-character budget. type: boolean values: description: >- At least one shown text or binary value was cut at 2,000 characters; a cut value ends with `[cut: ...]`. type: boolean required: - rows - values - capture type: object headers: X-Request-ID: description: >- The ID of the request. It is the `X-Request-ID` value that you sent, or an ID that the server made. Give it when you report a problem. schema: type: string securitySchemes: bearerAuth: description: >- A personal access token, which starts with `pat_`. A Parable token can call each operation that the roles of its owner allow. An MCP token can call only the read operations that are open to agents. A SQL token does not work on this API. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.