Skip to main content

​
API Reference

The Foil API provides programmatic access to traces, alerts, analytics, and more.

​
Base URL

https://api.getfoil.ai/api
For self-hosted deployments, use your instance URL.

​
Authentication

Foil supports two authentication methods:

​
JWT Bearer Token

For dashboard and user-authenticated requests: 
curl -X GET https://api.getfoil.ai/api/users/profile \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
Obtain a JWT token via the login endpoint: 
POST /api/auth/login
{
  "email": "[email protected]",
  "password": "your-password"
}

​
API Key

For SDK and programmatic access: 
curl -X POST https://api.getfoil.ai/api/signals \
  -H "x-api-key: sk_live_xxx_yyy" \
  -H "Content-Type: application/json" \
  -d '{"signalName": "user_rating", "value": 5}'
API keys are created in the dashboard under Settings > API Keys.
API keys provide full access to your data. Keep them secure and never expose them in client-side code.

​
Rate Limits

TierLimitEndpoints
Standard100 req/minUsers, Analytics, Agents, Events
Strict20 req/minAPI Keys, Admin
Ingestion500 req/minSpans, Signals, Logs
Rate limit headers are included in responses: 
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1704067200

​
Response Format

All responses are JSON with consistent structure:

​
Success Response

{
  "success": true,
  "data": { ... }
}

​
Error Response

{
  "success": false,
  "error": {
    "message": "Description of what went wrong",
    "code": "ERROR_CODE"
  }
}

​
Common Error Codes

CodeHTTP StatusDescription
UNAUTHORIZED401Missing or invalid authentication
FORBIDDEN403Insufficient permissions
NOT_FOUND404Resource doesn’t exist
VALIDATION_ERROR400Invalid request parameters
RATE_LIMITED429Too many requests
INTERNAL_ERROR500Server error

​
Pagination

List endpoints support pagination: 
GET /api/spans/traces?limit=50&skip=100
ParameterDefaultDescription
limit50Number of items per page (max 100)
skip0Number of items to skip
Response includes pagination info: 
{
  "data": [...],
  "pagination": {
    "total": 1250,
    "limit": 50,
    "skip": 100,
    "hasMore": true
  }
}

​
Date Filtering

Most endpoints accept date filters: 
GET /api/analytics/metrics?startDate=2024-01-01&endDate=2024-01-31
Dates should be in ISO 8601 format: YYYY-MM-DD or YYYY-MM-DDTHH:mm:ssZ

​
Core Endpoints

​
Authentication

MethodEndpointDescription
POST/auth/loginUser login
POST/auth/registerUser registration
POST/auth/forgot-passwordRequest password reset
POST/auth/reset-passwordReset password with token
GET/auth/verify-emailVerify email address

​
API Keys

MethodEndpointDescription
POST/keysCreate new API key
GET/keysList all API keys
PUT/keys/:id/refreshRotate API key
POST/keys/:id/revokeRevoke API key
DELETE/keys/:idDelete API key

​
Spans & Traces

MethodEndpointDescription
GET/spans/tracesList traces (root spans)
GET/spans/traces/:traceIdGet trace with all spans
GET/spans/filtersGet available filter options

​
Signals

MethodEndpointDescription
POST/signalsRecord a signal
POST/signals/batchRecord multiple signals
GET/signalsList signals
GET/signals/summaryGet signal aggregations
GET/signals/trace/:traceIdGet signals for trace

​
Agents

MethodEndpointDescription
GET/agentsList all agents
POST/agentsCreate agent
GET/agents/:agentIdGet agent
PUT/agents/:agentIdUpdate agent
DELETE/agents/:agentIdDelete agent
PUT/agents/:agentId/alertsUpdate alert settings

​
Alerts

MethodEndpointDescription
GET/spans/alertsList all alerts
GET/spans/alerts/summaryAlert summary by agent
GET/spans/alerts/:alertIdGet alert details
PUT/spans/alerts/:alertId/acknowledgeAcknowledge alert
PUT/spans/alerts/:alertId/reopenReopen alert

​
Analytics

MethodEndpointDescription
GET/analytics/metricsDashboard metrics
GET/analytics/traces/success-failureSuccess/failure rates
GET/analytics/traces/requests-over-timeRequest volume
GET/analytics/traces/latency-percentilesLatency metrics
GET/analytics/traces/token-usageToken consumption
GET/analytics/costsCost breakdown

​
Experiments

MethodEndpointDescription
GET/experimentsList experiments
POST/experimentsCreate experiment
GET/experiments/:idGet experiment
POST/experiments/:id/startStart experiment
POST/experiments/:id/pausePause experiment
POST/experiments/:id/stopStop experiment
GET/experiments/:id/assignGet variant assignment
GET/experiments/:id/resultsGet experiment results

​
SDKs

For easier integration, use our official SDKs:

JavaScript SDK

npm install @foil-ai/sdk

Python SDK

pip install foil-sdk