Analytics

How the agent is being used and where it fails.

Base URL https://futuresmart.ai/database-agent/api · every request sends X-API-Key. Samples read the key from DATABASE_AGENT_API_KEY. All endpoints

Get usage statistics

GET/v1/agents/{agent_id}/statistics

Get statistics for a specific agent

Credential Database Agent API key for this agent (X-API-Key)

Path parameters

Name	Type	Description
`agent_id`required	`string`

Query parameters

Name	Type	Description
`start_time`	`string \| null`	Start time for statistics (ISO format)
`end_time`	`string \| null`	End time for statistics (ISO format)

Other responses

422 Validation Error

import os
import requests

API_ROOT = "https://futuresmart.ai/database-agent/api"
API_KEY = os.environ["DATABASE_AGENT_API_KEY"]

r = requests.get(
    f"{API_ROOT}/v1/agents/YOUR_AGENT_ID/statistics",
    headers={"X-API-Key": API_KEY},
    timeout=120,
)
r.raise_for_status()
print(r.json())

const API_ROOT = "https://futuresmart.ai/database-agent/api";

const res = await fetch(`${API_ROOT}/v1/agents/YOUR_AGENT_ID/statistics`, {
  method: "GET",
  headers: { "X-API-Key": process.env.DATABASE_AGENT_API_KEY },
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());

curl -X GET "https://futuresmart.ai/database-agent/api/v1/agents/YOUR_AGENT_ID/statistics" \
  -H "X-API-Key: $DATABASE_AGENT_API_KEY"

Analytics Scorecard

GET/v1/agents/{agent_id}/analytics/scorecard

Everything for one agent in one response: usage, quality (answered/failed), routing (SQL vs cross-DB vs pandas, and per-database), performance (latency incl. time inside the customer database), cost, tokens. Pass start_date+end_date for a custom range, else period. bucket sets the usage.per_day granularity (use hour for intraday time-of-day activity).

Credential Database Agent API key for this agent (X-API-Key)

Path parameters

Name	Type	Description
`agent_id`required	`string`	Agent ID

Query parameters

Name	Type	Description
`period`	`string`	Default: week
`bucket`	`string`	usage.per_day granularity: hour \| day \| week \| monthDefault: day
`start_date`	`string (date-time) \| null`	Custom range start (ISO-8601); with end_date overrides period
`end_date`	`string (date-time) \| null`	Custom range end, exclusive (ISO-8601)
`top_n`	`integer`	Default: 10

Other responses

422 Validation Error

import os
import requests

API_ROOT = "https://futuresmart.ai/database-agent/api"
API_KEY = os.environ["DATABASE_AGENT_API_KEY"]

r = requests.get(
    f"{API_ROOT}/v1/agents/YOUR_AGENT_ID/analytics/scorecard",
    headers={"X-API-Key": API_KEY},
    timeout=120,
)
r.raise_for_status()
print(r.json())

const API_ROOT = "https://futuresmart.ai/database-agent/api";

const res = await fetch(`${API_ROOT}/v1/agents/YOUR_AGENT_ID/analytics/scorecard`, {
  method: "GET",
  headers: { "X-API-Key": process.env.DATABASE_AGENT_API_KEY },
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());

curl -X GET "https://futuresmart.ai/database-agent/api/v1/agents/YOUR_AGENT_ID/analytics/scorecard" \
  -H "X-API-Key: $DATABASE_AGENT_API_KEY"

Analytics Failures

GET/v1/agents/{agent_id}/analytics/failures

Failure category/stage/database breakdown + the most-repeated failed queries.

Credential Database Agent API key for this agent (X-API-Key)

Path parameters

Name	Type	Description
`agent_id`required	`string`	Agent ID

Query parameters

Name	Type	Description
`period`	`string`	Default: week
`start_date`	`string (date-time) \| null`	Custom range start (ISO-8601); with end_date overrides period
`end_date`	`string (date-time) \| null`	Custom range end, exclusive (ISO-8601)
`category`	`string \| null`	sql_error \| db_connection \| no_rows \| sql_generation \| out_of_scope \| unanswered \| exception
`failed_stage`	`string \| null`	Node the failure is attributed to: router \| db_router \| sql_gen \| sql_exec \| final_answer \| chat_api
`limit`	`integer`	Default: 50
`offset`	`integer`	Default: 0

Other responses

422 Validation Error

import os
import requests

API_ROOT = "https://futuresmart.ai/database-agent/api"
API_KEY = os.environ["DATABASE_AGENT_API_KEY"]

r = requests.get(
    f"{API_ROOT}/v1/agents/YOUR_AGENT_ID/analytics/failures",
    headers={"X-API-Key": API_KEY},
    timeout=120,
)
r.raise_for_status()
print(r.json())

const API_ROOT = "https://futuresmart.ai/database-agent/api";

const res = await fetch(`${API_ROOT}/v1/agents/YOUR_AGENT_ID/analytics/failures`, {
  method: "GET",
  headers: { "X-API-Key": process.env.DATABASE_AGENT_API_KEY },
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());

curl -X GET "https://futuresmart.ai/database-agent/api/v1/agents/YOUR_AGENT_ID/analytics/failures" \
  -H "X-API-Key: $DATABASE_AGENT_API_KEY"

Analytics Trends

GET/v1/agents/{agent_id}/analytics/trends

Bucketed trend series + a server-side regression flag, plus the full current-vs-previous-period comparison for every headline metric. Pass start_date+end_date for a custom range (bucketed by bucket), else the trailing weeks window.

Credential Database Agent API key for this agent (X-API-Key)

Path parameters

Name	Type	Description
`agent_id`required	`string`	Agent ID

Query parameters

Name	Type	Description
`weeks`	`integer`	Default: 8
`bucket`	`string`	Default: week
`metrics`	`string \| null`	csv subset of success_rate,avg_ms,p95_ms,cost,failures,total_queries
`start_date`	`string (date-time) \| null`	Custom range start (ISO-8601); with end_date overrides the trailing `weeks` window
`end_date`	`string (date-time) \| null`	Custom range end, exclusive (ISO-8601)

Other responses

422 Validation Error

import os
import requests

API_ROOT = "https://futuresmart.ai/database-agent/api"
API_KEY = os.environ["DATABASE_AGENT_API_KEY"]

r = requests.get(
    f"{API_ROOT}/v1/agents/YOUR_AGENT_ID/analytics/trends",
    headers={"X-API-Key": API_KEY},
    timeout=120,
)
r.raise_for_status()
print(r.json())

const API_ROOT = "https://futuresmart.ai/database-agent/api";

const res = await fetch(`${API_ROOT}/v1/agents/YOUR_AGENT_ID/analytics/trends`, {
  method: "GET",
  headers: { "X-API-Key": process.env.DATABASE_AGENT_API_KEY },
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());

curl -X GET "https://futuresmart.ai/database-agent/api/v1/agents/YOUR_AGENT_ID/analytics/trends" \
  -H "X-API-Key: $DATABASE_AGENT_API_KEY"

Analytics Queries

GET/v1/agents/{agent_id}/analytics/queries

Per-query drill-down — slowest / most-expensive / failure investigation, each row carrying the SQL it ran, the database it used and its per-node spend. Pass start_date+end_date for a custom range, else period (both ignored when chat_id is set).

Credential Database Agent API key for this agent (X-API-Key)

Path parameters

Name	Type	Description
`agent_id`required	`string`	Agent ID

Query parameters

Name	Type	Description
`period`	`string`	Default: week
`sort`	`string`	Default: latency_ms
`order`	`string`	Default: desc
`status`	`string \| null`	answered \| unanswered
`outcome`	`string \| null`	success \| failure
`failure_category`	`string \| null`
`failed_stage`	`string \| null`
`route`	`string \| null`	sql \| cross_db \| pandas \| direct_answer
`model`	`string \| null`
`db_id`	`string \| null`	Only queries routed to this database
`min_tokens`	`integer \| null`
`min_cost_usd`	`number \| null`
`min_latency_ms`	`integer \| null`
`chat_id`	`string \| null`
`feedback`	`string \| null`	Filter by user feedback: positive \| negative \| none (unrated) \| any (rated)
`include_node_data`	`boolean`	Include the per-node breakdown (metrics.node_data) in each row; set false for a lean listDefault: true
`start_date`	`string (date-time) \| null`	Custom range start (ISO-8601); with end_date overrides period (ignored when chat_id is set)
`end_date`	`string (date-time) \| null`	Custom range end, exclusive (ISO-8601)
`limit`	`integer`	Default: 20
`offset`	`integer`	Default: 0

Other responses

422 Validation Error

import os
import requests

API_ROOT = "https://futuresmart.ai/database-agent/api"
API_KEY = os.environ["DATABASE_AGENT_API_KEY"]

r = requests.get(
    f"{API_ROOT}/v1/agents/YOUR_AGENT_ID/analytics/queries",
    headers={"X-API-Key": API_KEY},
    timeout=120,
)
r.raise_for_status()
print(r.json())

const API_ROOT = "https://futuresmart.ai/database-agent/api";

const res = await fetch(`${API_ROOT}/v1/agents/YOUR_AGENT_ID/analytics/queries`, {
  method: "GET",
  headers: { "X-API-Key": process.env.DATABASE_AGENT_API_KEY },
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());

curl -X GET "https://futuresmart.ai/database-agent/api/v1/agents/YOUR_AGENT_ID/analytics/queries" \
  -H "X-API-Key: $DATABASE_AGENT_API_KEY"