Skip to main content
The Foveus API lets SDKs and services send telemetry to your workspace and retrieve observability data from the dashboard. Most teams do not need to call the API directly at first. Start with the .NET SDK: 
builder.Services.AddFoveus("fov_test_...");
app.UseFoveus();
The SDK handles authentication, batching, retries, capture, redaction, and ingestion.

​
When to use the API directly

Use the API directly when you need to:
  • build a custom SDK or integration
  • ingest telemetry from a platform Foveus does not support yet
  • automate workspace setup
  • query executions programmatically
  • connect Foveus data to internal tools
  • build custom operational workflows
For most .NET services, use the SDK instead.

​
Authentication

Foveus API requests use API keys. Test keys are created automatically during onboarding. 
fov_test_...
Live keys are created manually from Settings. 
fov_live_...
Send the key from your backend service only.
Do not expose Foveus API keys in frontend JavaScript, mobile apps, public repositories, logs, screenshots, or client-side applications.

​
Modes

Foveus separates telemetry into two modes.
ModeUse for
testLocal development, sandbox testing, QA, and onboarding
liveProduction telemetry
Foveus defaults to Test mode. Set Mode to live only when sending production telemetry with a live key.

​
Main API areas

The Foveus API is organized around telemetry and investigation workflows.
AreaPurpose
IngestionSend executions, logs, metrics, context, and issue evidence.
ExecutionsQuery execution records and open execution details.
IssuesQuery grouped failure patterns and linked executions.
LogsQuery logs correlated to executions.
MetricsQuery aggregated service and system metrics.
WorkspaceManage workspace-level configuration and settings.
API keysManage live API keys and permissions.

​
Ingestion API

The ingestion API receives telemetry from SDKs and integrations. It can include:
  • execution metadata
  • request context
  • response context
  • logs
  • metrics
  • exceptions
  • outcome evidence
  • custom context
For most services, the SDK sends ingestion data automatically.

​
Executions API

The Executions API powers the Executions page. It can be used to query executions by:
  • service
  • status
  • method
  • endpoint
  • execution ID
  • trace ID
  • issue ID
  • duration
  • time range
  • indexed context fields
Example query shape: 
GET /api/executions?mode=test&serviceName=orders-api&page=1&pageSize=25
Context search uses indexed context fields: 
GET /api/executions?mode=test&serviceName=orders-api&context.customerId=cus_12345&includeMatchedContext=true&page=1&pageSize=25
In the dashboard search bar, the same search is written as: 
service:orders-api context:customerId="cus_12345"

​
Issues API

The Issues API powers issue triage views. Issues represent grouped failure patterns. An issue can include:
  • title
  • status
  • service
  • failure type
  • hypothesis
  • suggested fix
  • common factors
  • occurrence counts
  • linked executions
  • lifecycle timestamps
  • assignment
  • comments and activity
Use issues when you want to understand repeated or meaningful failure patterns.

​
Logs API

The Logs API powers log exploration and execution-linked logs. Logs are most useful when correlated to executions. Use linked logs to inspect log lines for one request, job, or operation instead of searching through unrelated streams.

​
Metrics API

The Metrics API powers dashboard and service metrics. Metrics can include:
  • request volume
  • failure rate
  • latency
  • service health
  • throughput
  • system trends
  • aggregated telemetry
Use metrics for trends and overview. Use executions for exact investigation.

​
Context search API

Execution Context Search lets you find executions by indexed business context. Example dashboard query: 
service:orders-api context:orderStatus.value=1
Equivalent API shape: 
GET /api/executions?mode=test&serviceName=orders-api&context.orderStatus.value=1&includeMatchedContext=true&page=1&pageSize=25
String values should be quoted in the dashboard query language: 
service:orders-api context:customerId="cus_12345"
When calling the API directly, URL-encode values where needed.

​
Pagination

List endpoints use pagination. Common parameters include:
ParameterDescription
pagePage number.
pageSizeNumber of items per page.
Example: 
GET /api/executions?mode=test&serviceName=orders-api&page=1&pageSize=25

​
Error responses

Foveus APIs return structured errors. Common error types may include:
ErrorMeaning
UNAUTHORIZEDThe API key or user session is invalid.
FORBIDDENThe caller does not have permission.
VALIDATION_ERRORThe request contains invalid fields.
CONTEXT_KEY_NOT_ALLOWEDThe context key is not enabled or allowed for search.
CONTEXT_QUERY_TOO_BROADThe context search is too broad without enough scope.
Error names may evolve during private beta.

​
Rate limits and guardrails

Foveus applies guardrails to protect workspace performance and ingestion reliability. These can include:
  • API key rate limits
  • request size limits
  • context indexing limits
  • maximum page size
  • maximum context keys per request
  • maximum values per key
  • time-window limits for broad context searches
These limits help keep searches predictable and safe.

​
Private beta note

The public API reference is still evolving during private beta. Use the SDK where possible. If you need direct API access, confirm the current endpoint contract with the Foveus team before building production workflows against it.

​
What to do next