> ## 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. # Search available data > Searches the Provider Pools for the tables, columns and fields that hold the data a question needs. 1. query is plain text. 2. scope narrows by name before ranking: providers.jiracloud is one Provider, providers.jiracloud.issues.* the columns of one table. 3. kind keeps tables or columns. 4. limit and offset page through at most 500 ranked results. Results rank by keyword; matchedBy says whether meaning also matched. 5. An empty query (or *) lists instead of searching. With no scope, providers holds every Provider the caller may query and its table count. With one Provider as scope, such as providers.jiracloud, matches holds its tables by name with their descriptions and row counts, limit a page (100 by default, at most 40,000 characters), and nextCursor, sent back as cursor, reads the next page. A listing covers the providers Pool, as a search does. The search reads names and descriptions, never rows. ## Access An MCP token or a Parable token can call this operation. See [Authentication](/getting-started/authentication.md) for the kinds of token. Your roles must grant `tenant.data.query.providers`. ## Errors * `HTTP 400`: The scope is not a dotted name that starts with providers or workspace, or the scope and kind can never match together. A listing was sent a column kind, an offset, a scope other than one Provider by name, or another listing's cursor; a search was sent a cursor. The message says what to change. A scope in a Pool the caller may not query is not an error: the search finds nothing. Start the scope with providers, such as providers.jiracloud or providers.\*.issues, or leave scope and kind out. A workspace scope finds nothing through this operation. Page a listing with nextCursor, and a search with offset. * `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 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. * `HTTP 504`: The statement ran past its time budget (a QL-TO code) or did not finish in 30 seconds. Narrow the scope or the statement, then send it again. ## OpenAPI ````yaml /api-reference/openapi.json post /api/provider-pool/search 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/search: post: tags: - Provider pool summary: Search available data description: >- Searches the Provider Pools for the tables, columns and fields that hold the data a question needs. 1. query is plain text. 2. scope narrows by name before ranking: providers.jiracloud is one Provider, providers.jiracloud.issues.* the columns of one table. 3. kind keeps tables or columns. 4. limit and offset page through at most 500 ranked results. Results rank by keyword; matchedBy says whether meaning also matched. 5. An empty query (or *) lists instead of searching. With no scope, providers holds every Provider the caller may query and its table count. With one Provider as scope, such as providers.jiracloud, matches holds its tables by name with their descriptions and row counts, limit a page (100 by default, at most 40,000 characters), and nextCursor, sent back as cursor, reads the next page. A listing covers the providers Pool, as a search does. The search reads names and descriptions, never rows. operationId: ProviderPoolSearchAvailableDataHandler 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/SearchAvailableDataInput' required: true responses: '200': content: application/json: schema: properties: data: $ref: '#/components/schemas/SearchAvailableDataResult' 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 { SearchAvailableDataInput } 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: SearchAvailableDataInput = JSON.parse(`{ "query": "example" }`); const result = await sdk.providerPool.searchAvailableData( input ); - label: Python SDK lang: python source: |- import json import os from parable_types_web_api import SearchAvailableDataInput 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 = SearchAvailableDataInput.model_validate( json.loads("{\"query\":\"example\"}"), ) result = sdk.provider_pool.search_available_data(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::SearchAvailableDataInput = serde_json::from_value( serde_json::json!({ "query": "example" }), )?; let result = sdk.provider_pool.search_available_data( 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.SearchAvailableDataInput\nif err := json.Unmarshal([]byte(`{\"query\":\"example\"}`), &input); err != nil {\n\treturn err\n}\nresult, err := sdk.ProviderPoolNamespace.SearchAvailableData(ctx, input)" components: schemas: SearchAvailableDataInput: description: |- A search of the data the caller may query, by the words a table's or a column's name and description would use, or, with an empty query, a listing of the tables they may query. properties: cursor: description: >- The nextCursor of the listing page before, to read the next one. Null starts a listing at its first table. A search takes none. maxLength: 1500 nullable: true type: string kind: description: Null returns tables and columns. A listing returns tables only. oneOf: - $ref: '#/components/schemas/AvailableDataKindEnum' - enum: - null nullable: true type: string limit: description: >- Results per page, 1 to 100. Null means 20 in a search and 100 in a listing. format: int64 maximum: 100 minimum: 1 nullable: true type: integer offset: description: >- Results to skip in a search, which ranks at most 500. Null means 0. A listing pages with cursor instead. format: int64 maximum: 499 minimum: 0 nullable: true type: integer query: description: >- Plain text describing the data, such as `open issues and who they are assigned to`. Empty or `*` lists the Provider Pool instead of searching it: each Provider with its table count, or with a scope such as `providers.jiracloud`, that Provider's tables. maxLength: 1000 type: string scope: description: >- A pattern over names that narrows the search before ranking, one dotted segment at a time: `providers.jiracloud` is one Provider, `providers.jiracloud.issues.*` the columns of one table, `providers.*.issues` the tables named issues in every Provider. Null searches every Pool the caller may query. A listing takes no scope, to list the Providers, or one Provider by name, to list its tables. maxLength: 500 nullable: true type: string required: - query type: object SearchAvailableDataResult: properties: limit: description: >- Signed 64-bit integer; range bounded by JavaScript's safe-integer ceiling. format: int64 maximum: 9007199254740991 minimum: -9007199254740991 type: integer matches: description: |- Best first in a search; in a listing, one Provider's tables by name. Fewer than `limit` in a search means it has no more results. items: $ref: '#/components/schemas/AvailableDataMatch' type: array nextCursor: description: >- A listing with more tables: send it back as cursor for the next page. Null on a listing's last page and in a search. nullable: true type: string offset: description: >- Signed 64-bit integer; range bounded by JavaScript's safe-integer ceiling. format: int64 maximum: 9007199254740991 minimum: -9007199254740991 type: integer providers: description: >- A listing with no scope: every Provider the caller may query, by scope, with its table count. Empty otherwise. items: $ref: '#/components/schemas/AvailableDataProvider' type: array required: - matches - providers - limit - offset 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 AvailableDataKindEnum: enum: - table - column type: string AvailableDataMatch: description: >- One table, column, or field inside a struct column that matched a search, or one table of a listing. properties: columnName: description: >- The column to select, quoted where SQL needs it, such as `priority` or `fields.assignee."displayName"`. Null for a table. nullable: true type: string dataType: description: The Arrow type, with its Parable scalar when it has one. nullable: true type: string description: nullable: true type: string kind: $ref: '#/components/schemas/AvailableDataKindEnum' matchedBy: description: '`keyword`, `semantic` or `both`; `listed` in a listing.' type: string pool: description: The Pool the match is in, such as `providers`. type: string provider: description: >- The Provider the data comes from. Null for a table that belongs to none, and in a listing, where tableRef names the Provider. nullable: true type: string qualifiedName: type: string rowCount: description: >- Rows in the table when maintenance last counted them, in a listing only. Null when the count is unknown, zero, or withheld by a Provider Policy. format: int64 maximum: 9007199254740991 minimum: -9007199254740991 nullable: true type: integer score: description: >- Relevance; higher is better, comparable within one search only. 0 in a listing. format: double type: number tableRef: description: The name to put in FROM, such as `providers.jiracloud.issues`. type: string required: - pool - kind - tableRef - qualifiedName - score - matchedBy type: object AvailableDataProvider: description: One Provider of a listing. properties: scope: description: >- The scope that lists this Provider's tables, such as `providers.jiracloud`. type: string tableCount: description: How many tables the Provider has in the providers Pool. format: int64 maximum: 9007199254740991 minimum: -9007199254740991 type: integer required: - scope - tableCount 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.