API Requests
This guide provides comprehensive examples for interacting with aiXplain's API endpoints across Models, Tools, and Agents.
This guide provides examples for interacting with aiXplain's production API endpoints.
Authentication
All API requests require an API key in the request header:
x-api-key: YOUR_API_KEY
Content-Type: application/json
Models API
Base URL: https://models.aixplain.com
Run model
Request:
POST https://models.aixplain.com/api/v2/execute/{model_id}
x-api-key: YOUR_API_KEY
Content-Type: application/json
{
"text": "What is 2 + 2?"
}
Run with parameters
Request:
POST https://models.aixplain.com/api/v2/execute/{model_id}
x-api-key: YOUR_API_KEY
Content-Type: application/json
{
"text": "What are the colors of the rainbow?",
"max_tokens": 10,
"temperature": 0.8
}
Run with chat history
Request:
POST https://models.aixplain.com/api/v2/execute/{model_id}
x-api-key: YOUR_API_KEY
Content-Type: application/json
{
"text": [
{"role": "user", "content": "Hello!"},
{"role": "assistant", "content": "Hi there! How can I help?"},
{"role": "user", "content": "Tell me a fun fact."}
]
}
Poll for result (if needed)
Some models return a requestId for polling:
Request:
GET https://models.aixplain.com/api/v2/data/{request_id}
x-api-key: YOUR_API_KEY
Get model stats
Returns usage statistics for a model over a date range — total requests, success/failure counts, average latency, average tokens per request, and a per-API-key breakdown with hourly time series.
Request:
POST https://platform-api.aixplain.com/sdk/models/stats
x-api-key: YOUR_API_KEY
Content-Type: application/json
{
"startDay": "2026-03-24",
"endDay": "2026-04-20",
"modelId": "695fce4c27b4e3580e43d126"
}
startDay cannot be more than 31 days in the past. Add "apiKey": "..." to the body to filter results to one API key's activity.
Response:
A JSON array. Contains one result object when data exists; [] when no usage matches the filters (HTTP 201 is still returned in that case).
[
{
"modelId": "695fce4c27b4e3580e43d126",
"timeRange": { "start": "2026-03-24", "end": "2026-04-20" },
"aggregateMetrics": {
"totalRequests": 87384,
"successfulRequests": 73503,
"failedRequests": 13881,
"avgLatencyMs": 1,
"avgTokensPerRequest": 1623.17
},
"metricsByApiKey": [
{
"apiKey": "0a0e********94c1",
"owned": true,
"aggregateMetrics": {
"totalRequests": 75,
"successfulRequests": 75,
"failedRequests": 0,
"avgLatencyMs": 2.70,
"avgTokensPerRequest": 2121.01
},
"timeSeries": [
{
"timestamp": "2026-04-03T14:00:00.000Z",
"requests": 6,
"successfulRequests": 6,
"avgLatencyMs": 0.88,
"avgTokensPerRequest": 491.5
}
]
}
]
}
]
| Response field | Description |
|---|---|
aggregateMetrics.totalRequests | All requests in the window. |
aggregateMetrics.successfulRequests | Requests that completed without error. |
aggregateMetrics.failedRequests | Requests that returned an error. |
aggregateMetrics.avgLatencyMs | Mean latency in milliseconds. |
aggregateMetrics.avgTokensPerRequest | Mean token count (input + output) per request. |
metricsByApiKey[].apiKey | Masked API key string identifying the consumer. |
metricsByApiKey[].owned | true if the key belongs to the authenticated caller. |
metricsByApiKey[].aggregateMetrics | Same metric shape as the top-level aggregate, scoped to this key. |
timeSeries[].timestamp | ISO 8601 UTC timestamp for the start of the hour bucket. |
timeSeries[].requests | Total requests in that hour. |
timeSeries[].successfulRequests | Successful requests in that hour. |
timeSeries[].avgLatencyMs | Mean latency for that hour. |
timeSeries[].avgTokensPerRequest | Mean token count for that hour. |
Python example:
import requests
from datetime import date, timedelta
today = date.today()
start = today - timedelta(days=14) # startDay cannot be more than 31 days in the past
response = requests.post(
"https://platform-api.aixplain.com/sdk/models/stats",
headers={"x-api-key": "YOUR_API_KEY", "Content-Type": "application/json"},
json={
"startDay": str(start),
"endDay": str(today),
"modelId": "695fce4c27b4e3580e43d126",
},
timeout=120,
)
data = response.json()
if data:
m = data[0]["aggregateMetrics"]
print(f"Total: {m['totalRequests']} Success: {m['successfulRequests']} Failed: {m['failedRequests']}")
for entry in data[0]["metricsByApiKey"]:
print(f" {entry['apiKey']}: {entry['aggregateMetrics']['totalRequests']} requests")
else:
print("No data for this model in the selected range")
Show output
Tools API
Base URL: https://models.aixplain.com
Run tool
Request:
POST https://models.aixplain.com/api/v2/execute/{tool_id}
x-api-key: YOUR_API_KEY
Content-Type: application/json
{
"action": "scrape",
"data": {
"url": "https://example.com"
}
}
Poll for result
Request:
GET https://models.aixplain.com/api/v2/data/{request_id}
x-api-key: YOUR_API_KEY
Agents API
Base URL: https://platform-api.aixplain.com
Run agent
Request:
POST https://platform-api.aixplain.com/v2/agents/{agent_id}/run
x-api-key: YOUR_API_KEY
Content-Type: application/json
{
"query": "What is 5 + 5?"
}
Poll for result
Request:
GET https://platform-api.aixplain.com/sdk/agents/{request_id}/result
x-api-key: YOUR_API_KEY
Multi-turn conversation (with session)
Request:
POST https://platform-api.aixplain.com/v2/agents/{agent_id}/run
x-api-key: YOUR_API_KEY
Content-Type: application/json
{
"query": "What was my previous question?",
"sessionId": "SESSION_ID_FROM_PREVIOUS_RESPONSE"
}
Multi-turn conversation (with history)
Request:
POST https://platform-api.aixplain.com/v2/agents/{agent_id}/run
x-api-key: YOUR_API_KEY
Content-Type: application/json
{
"query": "Continue from where we left off",
"history": [
{"role": "user", "content": "Help me plan a project"},
{"role": "assistant", "content": "Sure! What kind of project?"}
]
}