Get Query Result

curl --request GET \
--url 'https://mdb.ai/api/v1/conversations/123e4567-e89b-12d3-a456-426614174000/items/123e4567-e89b-12d3-a456-426614174001/result?limit=100&offset=0' \
--header 'Authorization: Bearer MINDS_API_KEY'

{
  "result": {
    "data": [
      [1, "John Doe", "[email protected]", 1000],
      [2, "Jane Smith", "[email protected]", 2000],
      [3, "Bob Johnson", "[email protected]", 1500]
    ],
    "column_names": ["id", "name", "email", "sales"]
  },
  "total": 150,
  "is_pagination_consistent": true
}

Export Query Result

curl --request GET \
--url 'https://mdb.ai/api/v1/conversations/123e4567-e89b-12d3-a456-426614174000/items/123e4567-e89b-12d3-a456-426614174001/export' \
--header 'Authorization: Bearer MINDS_API_KEY' \
--output results.csv

id,name,email,sales
1,John Doe,[email protected],1000
2,Jane Smith,[email protected],2000
3,Bob Johnson,[email protected],1500
...

Response Format

Get Query Result Response

The response contains three fields:

• result: An object containing:
  • data: Array of arrays, where each inner array represents a row of data
  • column_names: Array of strings representing the column names in order
• total: Total number of rows in the complete result set (not just the current page)
• is_pagination_consistent: Boolean indicating whether pagination is consistent. This is true if the SQL query has an ORDER BY clause, ensuring that results are returned in a consistent order across pages.

Export Query Result Response

The response is a CSV file with:

• Content-Type: text/csv
• First row: Column headers
• Subsequent rows: Data rows matching the query results

Pagination

When retrieving query results:

1. First Request: Use limit=100&offset=0 to get the first 100 rows
2. Subsequent Requests: Increment offset by the limit value to get the next page
   • Second page: limit=100&offset=100
   • Third page: limit=100&offset=200
   • And so on...

Note: For consistent pagination, ensure the SQL query includes an ORDER BY clause. Without it, is_pagination_consistent will be false, and results may appear in different orders across pages.

Error Responses

• 400 Bad Request:
  • Message is not an assistant message
  • Message does not have a SQL query
  • Invalid SQL query
  • Invalid pagination parameters
• 404 Not Found:
  • Conversation not found
  • Message not found
• 500 Internal Server Error: Unexpected error processing the request

Use Cases

1. Display Query Results in UI

Use the paginated result endpoint to display query results in a table with pagination:

GET /api/v1/conversations/{conversation_id}/items/{message_id}/result?limit=50&offset=0

2. Export Large Datasets

Use the export endpoint to download complete query results as CSV:

GET /api/v1/conversations/{conversation_id}/items/{message_id}/export

3. Process Results Programmatically

Fetch paginated results and process them in batches by incrementing the offset parameter with each request until all results are retrieved.

Notes

• Query results are retrieved by executing the SQL query stored in the assistant message
• The SQL query is validated to prevent SQL injection attacks
• For MSSQL databases, pagination is handled in memory due to MindsDB limitations
• Export endpoint returns all results without pagination limits
• CSV export includes UTF-8 encoding and proper header row