> ## 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. # Preview a Plot > Runs a Plot's query once and returns the rows it produces, without saving a Report. Use it to see what a Plot would show before relying on it. With a Parable's refId or commitId, the SQL reads that Parable's Plots under their Panes' Policies; only someone who may edit the Parable reads other pools from there, and never under View as. No row cap applies beyond the query row limit, which fails the query (QL-SQ-005); write a LIMIT in the SQL to bound the rows. Over HTTP the response body is an Arrow IPC stream (application/vnd.apache.arrow.stream) that is complete only when it ends with the IPC end-of-stream marker; a body that ends without it failed. A refusal is an RFC 9457 problem (application/problem+json). A tool caller receives ImmediatePlotQueryResult, holding at most 3 MiB of the stream's Arrow, with rowCount and truncated. ## Access This operation needs a Parable token. An MCP token cannot call it. See [Authentication](/getting-started/authentication.md) for the kinds of token. Your roles must grant one of `tenant.view`, `tenant.data.query.providers`. ## Errors * `HTTP 400`: The SQL, query parameters, reading, or selected data does not satisfy the Plot contract. When Parable refuses the SQL, the message gives the reason, and the code is a QL code, such as QL-PL-002 for a relation or table function the catalog does not serve. Correct the query using the stated reason, and select a valid current or Report reading. * `HTTP 403`: The caller, selected Workspace, or API token is not allowed to run this query. PA-AU-019 marks a refusal of the person's access: SQL that names no Parable needs the Provider Pools Reader or Data Access role; SQL in a Parable needs a seat on it and permission to read Parables, and reads beyond its Plots only with permission to edit it and a Publishing or Primary seat on it, never under View as; and a Plot's Pane Policies or a Provider Policy can refuse a table the SQL reads. Read only the Parable's Plots, or run the SQL without refId or commitId with the Provider Pools Reader or Data Access role, or use an identity with permission to edit the Parable and a Publishing or Primary seat on it. * `QL-TN-007`: The SQL names a Plot whose rows a Report run stored (a stored Refresh), and Provider Policies or source permissions narrow what the caller reads of a Provider table behind it. The Refresh holds rows the caller cannot read, so it is refused (HTTP 403). Do not run SQL over that Plot again as this caller. Other SQL over it gets the same refusal. Someone whom no Provider Policy or source permissions narrow on those tables can read it. * `QL-SQ-010`: The query would send more paid AI calls (ponder, embed and the Jev functions) than one query may send, so it stopped before the next call (HTTP 400). The message names the limit and the function. Filter, sample or LIMIT the rows before the AI function, or aggregate fewer rows. To call it over every row, publish the SQL as a Plot. * `QL-SQ-011`: The query's paid AI calls would cost more than one query may spend, so it stopped before the next call (HTTP 400). The message names the limit and what the query spent. Call the AI function over fewer rows or with a cheaper model. To call it over every row, publish the SQL as a Plot. * `HTTP 404`: The requested Parable ref or published pin is not available in this Workspace. Check the ref or commit ID and Workspace context. * `HTTP 409`: The Plot definition or access changed while the query was being prepared. With PA-AU-028, the commitId names a change that has not been published, so there is no Version to run SQL in. Refresh the Plot context and retry, or use a published Version's commitId. ## OpenAPI ````yaml /api-reference/openapi.json post /api/parables/immediate-plot-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/parables/immediate-plot-query: post: tags: - Parables summary: Preview a Plot description: >- Runs a Plot's query once and returns the rows it produces, without saving a Report. Use it to see what a Plot would show before relying on it. With a Parable's refId or commitId, the SQL reads that Parable's Plots under their Panes' Policies; only someone who may edit the Parable reads other pools from there, and never under View as. No row cap applies beyond the query row limit, which fails the query (QL-SQ-005); write a LIMIT in the SQL to bound the rows. Over HTTP the response body is an Arrow IPC stream (application/vnd.apache.arrow.stream) that is complete only when it ends with the IPC end-of-stream marker; a body that ends without it failed. A refusal is an RFC 9457 problem (application/problem+json). A tool caller receives ImmediatePlotQueryResult, holding at most 3 MiB of the stream's Arrow, with rowCount and truncated. operationId: ParablesExecuteImmediatePlotQueryHandler 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/ImmediatePlotQueryInput' required: true responses: '200': content: application/vnd.apache.arrow.stream: schema: format: binary type: string description: Successful response, streamed as application/vnd.apache.arrow.stream 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' security: - bearerAuth: [] x-codeSamples: - label: TypeScript SDK lang: typescript source: >- import { WebApiSDK } from "@parable-platform/web-api-sdk"; import type { ImmediatePlotQueryInput } 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: ImmediatePlotQueryInput = JSON.parse(`{ "sql": "example" }`); const result = await sdk.parables.executeImmediatePlotQuery( input ); - label: Python SDK lang: python source: |- import json import os from parable_types_web_api import ImmediatePlotQueryInput 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 = ImmediatePlotQueryInput.model_validate( json.loads("{\"sql\":\"example\"}"), ) result = sdk.parables.execute_immediate_plot_query(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::ImmediatePlotQueryInput = serde_json::from_value( serde_json::json!({ "sql": "example" }), )?; let result = sdk.parables.execute_immediate_plot_query( 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.ImmediatePlotQueryInput\nif err := json.Unmarshal([]byte(`{\"sql\":\"example\"}`), &input); err != nil {\n\treturn err\n}\nresult, err := sdk.ParablesNamespace.ExecuteImmediatePlotQuery(ctx, input)" components: schemas: ImmediatePlotQueryInput: description: >- One SQL statement to run once against the Workspace's data. The operation caps no rows. The result is every row the statement returns, up to the query row limit, which fails the query rather than truncating it (QL-SQ-005). To read fewer rows, write a LIMIT in the SQL. A reader may also stop reading early: the Parable app stops at its display limit and an MCP tool call at 3 MiB of Arrow. properties: commitId: description: UUID v4 with automatic base62 encoding for client-facing APIs nullable: true pattern: >- ^([0-9A-Za-z]{1,22}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ type: string expectedRefRevision: description: >- Draft definition revision observed by the React host. Requires refId; execution refuses a stale revision instead of relabeling old code as new. Omitted means the caller deliberately requests the latest authorized ref. format: int64 maximum: 9007199254740991 minimum: 1 nullable: true type: integer jev: description: >- Jev defaults for this query only. SQL model arguments override the default. The null policy applies to recoverable input, provider and response failures. oneOf: - $ref: '#/components/schemas/JevSessionOptions' - enum: - null nullable: true type: object 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). Omitted/null/empty uses the ordinary unparameterized query path. items: description: 'Any valid JSON value: object, array, primitive, or null' nullable: true type: array reading: description: >- Host-selected data reading. Omitted raw SQL requests Current; a bound React Plot always sends its canonical context.data. Unsupported Report execution is refused explicitly rather than silently relabeled as Current. oneOf: - $ref: '#/components/schemas/PlotDataReading' - enum: - null nullable: true type: object refId: description: >- Where the Plot runs. At most one of the two: `refId` is the ref being viewed (a Proposal draft, or a Personal-mode root), `commitId` is a published line's pin. Parable uses them to choose the Parable-scope rows that `workspace.preferences` serves. Both absent means the Plot reads no Preferences. nullable: true pattern: >- ^([0-9A-Za-z]{1,22}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ type: string sql: description: >- Single SQL statement. Text.Sql rejects empty; maxLength is 100000 bytes. maxLength: 100000 minLength: 1 pattern: ^[\s\S]*$ type: string required: - sql 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 JevSessionOptions: additionalProperties: false description: >- Query-local controls. Credentials and the endpoint are server configuration. A null model leaves the choice to the Workspace model policy: the Workspace's SQL_JEV default, else the platform default. properties: model: nullable: true type: string on_error: $ref: '#/components/schemas/JevOnError' required: - on_error type: object PlotDataReading: description: >- Requested data reading, shared by React context and the Plot data protocol. REPORT_RUN requires reportRunId; CURRENT requires null. Boundary validation enforces this cross-field invariant in every executor. properties: kind: $ref: '#/components/schemas/PlotDataReadingKind' reportRunId: description: UUID v4 with automatic base62 encoding for client-facing APIs nullable: true pattern: >- ^([0-9A-Za-z]{1,22}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ type: string required: - kind type: object JevOnError: enum: - fail - 'null' type: string PlotDataReadingKind: description: A live reading or one concrete Report run. Draft previews use CURRENT. enum: - CURRENT - REPORT_RUN type: string 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.