# Chat Explore Our Chat Explore endpoints allow you to interface with Chat Explore, our flagship "chat with your data" assistant. Our API allows a programmatic interface by which you can supply a project or dataset and a question you'd like to ask about it, and we'll respond with an answer. As with most other long-running requests, we adopt an asynchronous endpoints model. You can read more about it on the [Asynchronous Endpoints](https://docs.akkio.com/akkio-docs/concepts/asynchronous-endpoints) page or continue reading here. ### Custom Instructions[​](https://api-docs.akkio.com/endpoints/chat-explore#custom-instructions) Chat Explore has the powerful capability for you to provide Custom Instructions that allow you to attach additional context for each call specific to your use case. {% hint style="info" %} **NOTE:** In order for Chat Explore to factor in custom instructions attached to the project into calls, you **must** make these calls with the `project_id` parameter rather than the `dataset_id` parameter. {% endhint %} Three parameters may be specified: * `chatContext`: What you'd like Chat Explore to know about your application to provide better responses. Examples: * This dataset is customer engagement data * The units of the sales column are in millions * `chatInstructions`: Specifics on how you'd like Chat Explore to respond. Examples: * Respond only in Spanish * Provide short and concise answers only * `chatSuggestions`: The Web UI (`app.akkio.com`) intelligently generates a list of example questions you may ask Chat Explore as a good starting point. You can customize these instructions by providing a newline-separated list of what you'd like these suggestions to be. Example: ``` What is the average net media cost by campaign ID? Please show me a chart of the distribution of customer ages. Please show me a bar chart of company size. ``` For information on programmatically updating these parameters for a given project, see the [Projects](https://docs.akkio.com/akkio-docs/endpoints-and-schemas/endpoints/broken-reference) endpoints page.
### Data Formatting[​](https://api-docs.akkio.com/endpoints/chat-explore#data-formatting) #### Images[​](https://api-docs.akkio.com/endpoints/chat-explore#images) Similar to the UI, we support returning charts and graphs to support our responses. Each message has an `images` field that represents a list of Base64-encoded images attached to that message. {% hint style="info" %} **NOTE:** Images are currently Base64 encoded in the `.png` format, but may be changed. You can assume a Base64-encoded image, but do not assume it will always be a `.png` image. {% endhint %} #### Tables[​](https://api-docs.akkio.com/endpoints/chat-explore#tables) Tables are returned as a List of \ maps, where each element of the list corresponds to a row, then each element has a key representing the column name and a value representing the value of that column. For example, here's how a two-row table of user objects might look like: ``` [ { "firstName": "John", "lastName": "Doe", "age": 23 }, { "firstName": "Joanna", "lastName": "Adams", "age": 45 } ] ``` Corresponding to this table:
firstNamelastNameage
JohnDoe23
JoannaAdams45
{% hint style="info" %} **NOTE:** Values can be anything JSON-serializable - strings, numbers, floats, and so on - not necessarily a string. {% endhint %} #### Statelessness[​](https://api-docs.akkio.com/endpoints/chat-explore#statelessness) Requests to this API are **stateless**. To emulate a full conversation, simply take our response from your previous query and add it to the `messages` array of your next query. You do *not* need to explicitly pass any kind of reference to your last query. *** ## Request Sequence Here's a rough outline of how you'd make a request to the Chat Explore API. #### HTTP Headers[​](https://api-docs.akkio.com/endpoints/chat-explore#http-headers)
Header NameRequiredValue
X-API-KeyYesYour team's API key. See Authentication.
### 1. Create Request[​](https://api-docs.akkio.com/endpoints/chat-explore#1-create-request) First, we'll submit a chat creation request. This will submit the task into our asynchronous processing queue and we'll begin working on it. ## Submit Chat Explore Query > Query Chat Explore through API. Takes in a list of messages and gives you the message Chat Explore sent back. ```json {"openapi":"3.1.0","info":{"title":"Akkio Public API (Beta)","version":"0.1.0"},"paths":{"/api/v1/chat-explore/new":{"post":{"description":"Query Chat Explore through API. Takes in a list of messages and gives you the message Chat Explore sent back.","operationId":"_submit_chat_explore_query_api_v1_chat_explore_new_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatExploreRequestPayload"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/APITaskStartedResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":" Submit Chat Explore Query","tags":["Chat Explore"]}}},"components":{"schemas":{"ChatExploreRequestPayload":{"additionalProperties":true,"properties":{"chatContext":{"default":"","description":"Anything you'd like Chat Explore to know about this application to provide better responses. For example: (1) This dataset is customer engagement data, (2) The units of the sales column are in millions, (3) The data is messy and contains typos","title":"Chatcontext","type":"string"},"chatInstructions":{"default":"","title":"Chatinstructions","type":"string"},"dataset_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The dataset ID which you want to run a Chat Explore query against. Either this or project_id must be specified.","title":"Dataset Id"},"messages":{"description":"A list of messages to query Chat Explore with.","items":{"$ref":"#/components/schemas/APIChatMessage"},"title":"Messages","type":"array"},"project_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The project ID which you want to run a Chat Explore query against. Either this or dataset_id must be specified; if this is specified, custom instructions attached to the project will be provided as context to the query.","title":"Project Id"}},"required":["messages"],"title":"ChatExploreRequestPayload","type":"object"},"APIChatMessage":{"additionalProperties":true,"properties":{"content":{"description":"The text content of this message.","title":"Content","type":"string"},"images":{"default":[],"description":"List of images for this message (potentially of length zero). May be exposed either as a base64 string or as stringified Plotly JSON, typically if the user requested it as such.","items":{"anyOf":[{"type":"string"},{"type":"object"}]},"title":"Images","type":"array"},"role":{"$ref":"#/components/schemas/RolesEnum","description":"The role of this message. User indicates the user sent the message, assistant indicates the assistant sent the message."},"table":{"anyOf":[{"items":{"type":"object"},"type":"array"},{"type":"null"}],"description":"If there exists a table for this message, this will be set to a list of objects/records, where each record has a key of the column name and a value for that row's corresponding value for the column.","title":"Table"}},"required":["role","content"],"title":"APIChatMessage","type":"object"},"RolesEnum":{"enum":["user","assistant"],"title":"RolesEnum","type":"string"},"APITaskStartedResponse":{"additionalProperties":true,"properties":{"task_id":{"description":"The ID of the task that was started. This is generally queryable at a nearby `/status` endpoint to get the current status of the task.","title":"Task Id","type":"string"}},"required":["task_id"],"title":"APITaskStartedResponse","type":"object"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}}} ``` You'll receive an object like this containing a task id: ``` { "task_id": "" } ``` We'll use this in the next request. ### 2. Query for Task Status[​](https://api-docs.akkio.com/endpoints/chat-explore#2-query-for-task-status) Next, we'll query the status endpoint at a cadence to see whether the chat is done being created yet. Note that you must use the same Task ID that you received from the task creation endpoint above. ## Get Chat Explore Status > Retrieves the status of the provided Chat Explore task id. ```json {"openapi":"3.1.0","info":{"title":"Akkio Public API (Beta)","version":"0.1.0"},"paths":{"/api/v1/chat-explore/status/{task_id}":{"get":{"description":"Retrieves the status of the provided Chat Explore task id.","operationId":"_get_chat_explore_status_api_v1_chat_explore_status__task_id__get","parameters":[{"in":"path","name":"task_id","required":true,"schema":{"title":"Task Id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIStatusResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":" Get Chat Explore Status","tags":["Chat Explore"]}}},"components":{"schemas":{"APIStatusResponse":{"additionalProperties":true,"properties":{"metadata":{"description":"Metadata, contextually dependent on the status of the task being queried.","discriminator":{"mapping":{"FAILED":"#/components/schemas/APIStatusMetadataFailed","IN_PROGRESS":"#/components/schemas/APIStatusMetadataInProgress","PENDING":"#/components/schemas/APIStatusMetadataPending","SUCCEEDED":"#/components/schemas/APIStatusMetadataSucceeded"},"propertyName":"type"},"oneOf":[{"$ref":"#/components/schemas/APIStatusMetadataPending"},{"$ref":"#/components/schemas/APIStatusMetadataInProgress"},{"$ref":"#/components/schemas/APIStatusMetadataSucceeded"},{"$ref":"#/components/schemas/APIStatusMetadataFailed"}],"title":"Metadata"},"status":{"$ref":"#/components/schemas/TaskStatusEnum","description":"The current status of the task being queried."}},"required":["status","metadata"],"title":"APIStatusResponse","type":"object"},"APIStatusMetadataPending":{"additionalProperties":true,"properties":{"type":{"const":"PENDING","default":"PENDING","enum":["PENDING"],"title":"Type","type":"string"}},"title":"APIStatusMetadataPending","type":"object"},"APIStatusMetadataInProgress":{"additionalProperties":true,"properties":{"estimate_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"If provided, an estimate of how many seconds we expect this task to take. This value should be treated as a rough estimate on a best-effort basis, not a guarantee.","title":"Estimate Seconds"},"type":{"const":"IN_PROGRESS","default":"IN_PROGRESS","enum":["IN_PROGRESS"],"title":"Type","type":"string"}},"title":"APIStatusMetadataInProgress","type":"object"},"APIStatusMetadataSucceeded":{"additionalProperties":true,"properties":{"location":{"description":"The path at which you can submit a GET request to retrieve the result of the successful job. May require proper authentication or authorization to access.","title":"Location","type":"string"},"type":{"const":"SUCCEEDED","default":"SUCCEEDED","enum":["SUCCEEDED"],"title":"Type","type":"string"}},"required":["location"],"title":"APIStatusMetadataSucceeded","type":"object"},"APIStatusMetadataFailed":{"additionalProperties":true,"properties":{"error":{"default":"Unable to complete request. Please verify your inputs, try again later, or get in touch at support@akkio.com.","description":"If provided, a text representation of what went wrong with the task, including if any action on your part may rectify the issue.","title":"Error","type":"string"},"type":{"const":"FAILED","default":"FAILED","enum":["FAILED"],"title":"Type","type":"string"}},"title":"APIStatusMetadataFailed","type":"object"},"TaskStatusEnum":{"description":"Celery task status enum. Update apps/web-backend-api/src/types/TaskStatusEnum.ts if you update this enum.","enum":["PENDING","IN_PROGRESS","SUCCEEDED","FAILED","UNKNOWN_TIMEOUT"],"title":"TaskStatusEnum","type":"string"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}}} ``` This will provide you with a `status` field set to either `SUBMITTED`, `IN_PROGRESS`, `FAILED`, or `SUCCEEDED`. You can read more about each state on the [Asynchronous Endpoints](https://docs.akkio.com/akkio-docs/endpoints-and-schemas/endpoints/broken-reference) page. You should retry ("poll") this endpoint at a regular cadence until you get a response that looks something like this: ``` { "status": "SUCCEEDED", "metadata": { "type": "SUCCEEDED", "location": "/api/v1/chat-explore/chats/" } } ``` {% hint style="info" %} **NOTE:** The `location` field is always relative to the **API root** (`https://api.akkio.com/api/v1`), *not* the overall website root (`https://api.akkio.com`). You'll need to remember to construct the end URL from the site name, API root, and the provided location. {% endhint %} Or, as a cURL command: ``` curl https://api.akkio.com/api/v1/chat-explore/status/task_id_from_previous_result \ -H "X-API-Key: your_api_key" ``` Armed with this information, we'll move to the last request. ### 3. Query for Result[​](https://api-docs.akkio.com/endpoints/chat-explore#3-query-for-result) Armed with the location we got from the status call, we'll make a request for the end chat. ## Get Chat > Retrieves a chat by id. ```json {"openapi":"3.1.0","info":{"title":"Akkio Public API (Beta)","version":"0.1.0"},"paths":{"/api/v1/chat-explore/chats/{id}":{"get":{"description":"Retrieves a chat by id.","operationId":"_get_chat_api_v1_chat_explore_chats__id__get","parameters":[{"in":"path","name":"id","required":true,"schema":{"title":"Id","type":"string"}},{"in":"query","name":"image_format","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/ChatExploreImageFormat"},{"type":"null"}],"title":"Image Format"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/_ApiBaseChatRecord"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":" Get Chat","tags":["Chat Explore"]}}},"components":{"schemas":{"ChatExploreImageFormat":{"enum":["base64_png","plotly_json"],"title":"ChatExploreImageFormat","type":"string"},"_ApiBaseChatRecord":{"additionalProperties":true,"properties":{"_org":{"description":"Foreign key to the organization this object belongs to.","title":" Org","type":"string"},"_owner":{"description":"Foreign key to the user this object belongs to.","title":" Owner","type":"string"},"messages":{"description":"List of messages in the chat.","items":{"$ref":"#/components/schemas/APIChatMessage"},"title":"Messages","type":"array"}},"required":["_owner","_org","messages"],"title":"_ApiBaseChatRecord","type":"object"},"APIChatMessage":{"additionalProperties":true,"properties":{"content":{"description":"The text content of this message.","title":"Content","type":"string"},"images":{"default":[],"description":"List of images for this message (potentially of length zero). May be exposed either as a base64 string or as stringified Plotly JSON, typically if the user requested it as such.","items":{"anyOf":[{"type":"string"},{"type":"object"}]},"title":"Images","type":"array"},"role":{"$ref":"#/components/schemas/RolesEnum","description":"The role of this message. User indicates the user sent the message, assistant indicates the assistant sent the message."},"table":{"anyOf":[{"items":{"type":"object"},"type":"array"},{"type":"null"}],"description":"If there exists a table for this message, this will be set to a list of objects/records, where each record has a key of the column name and a value for that row's corresponding value for the column.","title":"Table"}},"required":["role","content"],"title":"APIChatMessage","type":"object"},"RolesEnum":{"enum":["user","assistant"],"title":"RolesEnum","type":"string"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}}} ``` {% hint style="info" %} **NOTE:** If you're interested in the images returned and you would prefer it to be formatted as a string-serialized Plotly JSON object instead of the default base64-encoded `.png`, pass in a `image_format=plotly_json` query parameter, and they'll be returned as such. {% endhint %} A successful response looks something like this: ``` { "owner": "", "org": "", "messages": [ { "role": "assistant", "content": "Let's create a scatter plot to visualize the relationship between the living area (in square feet) and the price of the properties.", "images": null, "table": null }, { "role": "assistant", "content": "A chart or table will be rendered here. Chat Explore doesn't have direct access to your chart, so it can't read what's on it.", "images": [ "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAArwAAAH0CAYAAADfWf7fAAAgAElEQVR4XuydBZhUVRvH/7uzXXR3CSKolI0BIgooAtLd3d3d3SXd0goifGIrCijSXdLNdkzs97xnmGU2WO7szs5s/O/zfM+HO+eec+7vnJn7u+9977ku0dHR0eBGAiRAAiRAAiRAAiRAAumUgAuFN52OLA [...] AAASUVORK5CYII=" ], "table": null } ] } ``` Or, as a cURL command: ``` curl https://api.akkio.com/api/v1/chat-explore/chats/ \ -H "X-API-Key: your_api_key" ``` You can take this result and use it however you wish. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.akkio.com/akkio-docs/endpoints-and-schemas/endpoints/chat-explore.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.