Home / API / Queries

Queries API

Execute natural language queries, retrieve results, manage query history, and work with query templates.

🔐 Base URL

https://api.datixlab.com/v1

📍 Query Execution

Execute Query

Send a natural language question and get results.

Request

POST /queries
Authorization: Bearer <api_key>

Request Body

{
  "question": "Show me total revenue by product for Q4 2024",
  "agent_id": "agent_abc123",
  "include_sql": true,
  "include_chart": true,
  "format": "json"
}

Parameters

Field	Type	Required	Description
question	string	Yes	Natural language question
agent_id	string	Yes	Agent to use for query
include_sql	boolean	No	Include generated SQL
include_chart	boolean	No	Include chart config
format	string	No	json \| csv \| excel

Response - 200 OK

{
  "id": "query_xyz789",
  "question": "Show me total revenue by product for Q4 2024",
  "sql": "SELECT product_name, SUM(amount) as total_revenue FROM orders...",
  "results": [
    {
      "product_name": "Enterprise Plan",
      "total_revenue": 450000
    },
    {
      "product_name": "Professional Plan",
      "total_revenue": 280000
    }
  ],
  "row_count": 2,
  "execution_time": 2.34,
  "chart": {
    "type": "bar",
    "x_axis": "product_name",
    "y_axis": "total_revenue",
    "title": "Revenue by Product - Q4 2024"
  },
  "created_at": "2024-12-15T10:30:00Z"
}

Get Query by ID

Retrieve a previously executed query.

Request

GET /queries/{query_id}
Authorization: Bearer <api_key>

Response - 200 OK

{
  "id": "query_xyz789",
  "question": "Show me total revenue by product for Q4 2024",
  "agent_id": "agent_abc123",
  "status": "completed",
  "sql": "SELECT product_name, SUM(amount) as...",
  "results": [...],
  "execution_time": 2.34,
  "created_at": "2024-12-15T10:30:00Z"
}

List Query History

Get query execution history.

Request

GET /queries?limit=50&offset=0&agent_id=agent_abc123
Authorization: Bearer <api_key>

Query Parameters

limit - Number of results (default: 50, max: 100)
offset - Pagination offset
agent_id - Filter by agent
status - Filter by status (completed, failed, running)
start_date - Filter by date (ISO 8601)
end_date - Filter by date (ISO 8601)

Response - 200 OK

{
  "queries": [
    {
      "id": "query_xyz789",
      "question": "Show me total revenue...",
      "agent_id": "agent_abc123",
      "status": "completed",
      "execution_time": 2.34,
      "row_count": 2,
      "created_at": "2024-12-15T10:30:00Z"
    }
  ],
  "total": 523,
  "limit": 50,
  "offset": 0
}

📝 Query Templates

List Templates

GET /templates
Authorization: Bearer <api_key>

Response - 200 OK

{
  "templates": [
    {
      "id": "tpl_abc123",
      "name": "Daily Revenue Summary",
      "description": "Total revenue and order count",
      "agent_id": "agent_abc123",
      "parameters": [
        {
          "name": "date",
          "type": "date",
          "required": true
        }
      ],
      "created_at": "2024-10-15T10:00:00Z"
    }
  ]
}

Get Template

GET /templates/{template_id}
Authorization: Bearer <api_key>

Execute Template

Run a template with parameters.

Request

POST /templates/{template_id}/execute
Authorization: Bearer <api_key>

Request Body

{
  "parameters": {
    "date": "2024-12-15",
    "region": "North America"
  }
}

Response - 200 OK

{
  "execution_id": "exec_xyz789",
  "template_id": "tpl_abc123",
  "parameters": {
    "date": "2024-12-15",
    "region": "North America"
  },
  "results": [...],
  "row_count": 25,
  "execution_time": 1.89,
  "created_at": "2024-12-15T11:00:00Z"
}

Create Template

POST /templates
Authorization: Bearer <api_key>

Request Body

{
  "name": "Regional Sales Report",
  "description": "Sales metrics by region",
  "agent_id": "agent_abc123",
  "query": "Show me sales for {{region}} on {{date}}",
  "parameters": [
    {
      "name": "date",
      "type": "date",
      "required": true,
      "default": "today"
    },
    {
      "name": "region",
      "type": "string",
      "required": false,
      "default": "all"
    }
  ]
}

Update Template

PATCH /templates/{template_id}
Authorization: Bearer <api_key>

Delete Template

DELETE /templates/{template_id}
Authorization: Bearer <api_key>

Schedule Template

Setup recurring execution.

Request

POST /templates/{template_id}/schedule
Authorization: Bearer <api_key>

Request Body

{
  "schedule": {
    "type": "daily",
    "time": "08:00",
    "timezone": "America/New_York",
    "days_of_week": [1, 2, 3, 4, 5]
  },
  "parameters": {
    "region": "North America"
  },
  "recipients": [
    "team@company.com"
  ],
  "format": "excel",
  "enabled": true
}

📊 Export Results

Export Query to CSV

GET /queries/{query_id}/export?format=csv
Authorization: Bearer <api_key>

Export Query to Excel

GET /queries/{query_id}/export?format=excel
Authorization: Bearer <api_key>

Export with Chart

GET /queries/{query_id}/export?format=excel&include_chart=true
Authorization: Bearer <api_key>

📝 Code Examples

Python

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}

# Execute query
response = requests.post(
    'https://api.datixlab.com/v1/queries',
    headers=headers,
    json={
        'question': 'Show me top 10 customers by revenue',
        'agent_id': 'agent_abc123',
        'include_sql': True
    }
)

result = response.json()
print(result['results'])
print(result['sql'])

# Execute template
response = requests.post(
    'https://api.datixlab.com/v1/templates/tpl_abc123/execute',
    headers=headers,
    json={
        'parameters': {
            'date': '2024-12-15',
            'region': 'EMEA'
        }
    }
)

print(response.json()['results'])

JavaScript/TypeScript

const headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
};

// Execute query
const response = await fetch('https://api.datixlab.com/v1/queries', {
    method: 'POST',
    headers,
    body: JSON.stringify({
        question: 'Show me top 10 customers by revenue',
        agent_id: 'agent_abc123',
        include_sql: true
    })
});

const result = await response.json();
console.log(result.results);
console.log(result.sql);

// Execute template
const templateResponse = await fetch(
    'https://api.datixlab.com/v1/templates/tpl_abc123/execute',
    {
        method: 'POST',
        headers,
        body: JSON.stringify({
            parameters: {
                date: '2024-12-15',
                region: 'EMEA'
            }
        })
    }
);

const templateResult = await templateResponse.json();
console.log(templateResult.results);

⚠️ Error Responses

Query Failed

{
  "error": {
    "code": "query_execution_failed",
    "message": "Unable to execute query",
    "details": {
      "sql_error": "Syntax error in SQL query",
      "query_id": "query_xyz789"
    }
  }
}

Invalid Agent

{
  "error": {
    "code": "invalid_agent",
    "message": "Agent not found or not accessible",
    "details": {
      "agent_id": "agent_invalid"
    }
  }
}

🎓 Best Practices

✅ Cache Results

Cache frequent queries to reduce API calls

✅ Use Templates

Templates are faster than ad-hoc queries

✅ Handle Errors

Implement retry logic for failures

✅ Paginate Results

Use limit/offset for large datasets

✅ Monitor Usage

Track API usage and costs

✅ Async Processing

Use webhooks for long-running queries

🚀 Next Steps

← Authentication API Next: Agents API →