> ## Documentation Index > Fetch the complete documentation index at: https://docs.snowleopard.ai/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve > Execute a natural language query against a Playground datafile and return the retrieved data. ## OpenAPI ````yaml playground_openapi.json post /datafiles/{datafile_id}/retrieve openapi: 3.1.0 info: title: SnowLeopard API description: Natural language querying capabilities over structured data version: 1.0.0 servers: - url: https://api.snowleopard.ai description: Production server security: - bearerAuth: [] paths: /datafiles/{datafile_id}/retrieve: post: summary: Retrieve complete query results description: >- Execute a natural language query against a Playground datafile and return the retrieved data. operationId: retrieve parameters: - name: datafile_id in: path required: true description: Unique identifier for the datafile to query schema: type: string requestBody: required: true content: application/json: schema: type: object required: - userQuery properties: userQuery: type: string description: >- Natural language query to execute against the Playground datafile example: How many superheroes are there? knownData: type: object description: >- Optional key-value pairs to provide additional context for Snow Leopard to use when answering the question. additionalProperties: true example: user_id: '12345' company_name: Acme Corp responses: '200': description: Successful query execution content: application/json: schema: $ref: '#/components/schemas/RetrieveResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '409': description: Query execution error (e.g. invalid SQL generated) content: application/json: schema: type: object required: - __type__ - callId - responseStatus - description properties: __type__: type: string enum: - apiError description: Type discriminator callId: type: string format: uuid description: Unique identifier for this API call responseStatus: type: string enum: - UNABLE_TO_UNDERSTAND_QUESTION - NOT_FOUND_IN_SCHEMA - INTERNAL_SERVER_ERROR - AUTHORIZATION_FAILED - LLM_ERROR - LLM_TOKEN_LIMIT_REACHED - DB_ERROR - DB_CONNECTION_ERROR - DB_SYNTAX_ERROR description: Status of the response description: type: string description: Error description '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' x-codeSamples: - lang: Python label: Asynchronous source: |- from snowleopard import AsyncSnowLeopardClient async def main(): client = AsyncSnowLeopardClient(api_key="{api_key}") response = await client.retrieve( datafile_id="{datafile_id}", user_query="How many superheroes are there?" ) print(response.data) - lang: Python label: Synchronous source: |- from snowleopard import SnowLeopardClient client = SnowLeopardClient(api_key="{api_key}") response = client.retrieve( datafile_id="{datafile_id}", user_query="How many superheroes are there?" ) print(response.data) - lang: TypeScript label: TypeScript source: | import { SnowLeopardClient } from '@snowleopard-ai/client'; const client = new SnowLeopardClient({ apiKey: 'your-api-key' }); const response = await client.retrieve({ datafileId: 'your-datafile-id', userQuery: 'How many superheroes are there?' }); console.log(response.data); await client.close(); components: schemas: RetrieveResponse: type: object required: - __type__ - callId - data - responseStatus properties: __type__: type: string enum: - retrieveResponse description: Type discriminator callId: type: string format: uuid description: Unique identifier for this API call data: type: array description: Array of query results or errors items: oneOf: - $ref: '#/components/schemas/SchemaData' title: schemaData - $ref: '#/components/schemas/ErrorSchemaData' title: errorSchemaData responseStatus: type: string enum: - SUCCESS description: Status of the API response SchemaData: type: object required: - __type__ - schemaId - schemaType - query - rows - querySummary - rowMax - isTrimmed properties: __type__: type: string enum: - schemaData description: Type discriminator schemaId: type: string description: Identifier for the schema/database queried schemaType: type: string description: Type of database (e.g. SQLite, PostgreSQL) example: SQLite query: type: string description: Generated SQL query that was executed rows: type: array description: Result rows from the query items: type: object additionalProperties: true querySummary: type: object description: Detailed explanation of the query properties: technical_details: type: string description: Technical explanation of the query logic non_technical_explanation: type: string description: Plain language explanation for non-technical users rowMax: type: integer description: Maximum number of rows that can be returned isTrimmed: type: boolean description: Whether the result set was trimmed due to size limits callId: type: string format: uuid description: Call identifier (optional) ErrorSchemaData: type: object required: - __type__ - schemaType - schemaId - query - error - querySummary properties: __type__: type: string enum: - errorSchemaData description: Type discriminator schemaId: type: string description: Identifier for the schema/database queried schemaType: type: string description: Type of database example: SQLite query: type: string description: Generated SQL query that failed error: type: string description: Error message from query execution querySummary: type: object description: Explanation of what the query was attempting to do properties: technical_details: type: string description: Technical explanation of the query logic non_technical_explanation: type: string description: Plain language explanation for non-technical users datastoreExceptionInfo: type: string nullable: true description: Additional datastore-specific error information callId: type: string format: uuid description: Call identifier (optional) APIError: type: object required: - __type__ - callId - code - description properties: __type__: type: string enum: - apiError description: Type discriminator callId: type: string format: uuid description: Unique identifier for this API call code: type: integer description: HTTP status code of the response description: type: string description: Error description responses: BadRequest: description: Bad request error (e.g. missing required request body field) content: application/json: schema: allOf: - $ref: '#/components/schemas/APIError' - properties: code: type: integer enum: - 400 Unauthorized: description: Authorization error (e.g. invalid or missing API key) content: application/json: schema: allOf: - $ref: '#/components/schemas/APIError' - properties: code: type: integer enum: - 401 NotFound: description: Not found error. The requested datafile does not exist. content: application/json: schema: allOf: - $ref: '#/components/schemas/APIError' - properties: code: type: integer enum: - 404 InternalServerError: description: >- Internal server error. Retry your request, and contact your Snow Leopard admin if the issue continues. content: application/json: schema: allOf: - $ref: '#/components/schemas/APIError' - properties: code: type: integer enum: - 500 ServiceUnavailable: description: >- Service unavailable. The server is down for scheduled maintenance. Retry your request shortly. content: application/json: schema: allOf: - $ref: '#/components/schemas/APIError' - properties: code: type: integer enum: - 503 securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: api_key description: >- Bearer authentication header of the form `Bearer `, where `` is your auth API key. [Create an api_key](https://auth.snowleopard.ai/account/api_keys) ````