GET /projects/{project_reference}/tracesQuery project traces. Requires project.logs.read.
Servers
[
{
"url": "https://api.veryfront.com"
}
]Authentication
[
{
"bearerAuth": []
},
{
"apiKeyAuth": []
}
]{
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT or API Key",
"description": "Use a JWT bearer token or a Veryfront API key in the `Authorization` header."
},
"apiKeyAuth": {
"type": "apiKey",
"in": "header",
"name": "X-API-Key",
"description": "Alternative API key header for `vf_<prefix>_<secret>` tokens."
}
}Parameters
Parameter contracts
[
{
"schema": {
"type": "string",
"description": "Project slug or UUID. The resolved project is used to scope all trace reads server-side."
},
"required": true,
"name": "project_reference",
"in": "path"
},
{
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[A-Za-z0-9._-]+$",
"description": "Exact runtime environment tag, for example preview or production. Untagged telemetry is excluded."
},
"required": false,
"description": "Exact runtime environment tag, for example preview or production. Untagged telemetry is excluded.",
"name": "environment",
"in": "query"
},
{
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 253,
"pattern": "^[A-Za-z0-9.-]+(?::[0-9]+)?$",
"description": "Exact request host (without scheme or path), for example demo.preview.veryfront.com. Untagged telemetry is excluded."
},
"required": false,
"description": "Exact request host (without scheme or path), for example demo.preview.veryfront.com. Untagged telemetry is excluded.",
"name": "host",
"in": "query"
},
{
"schema": {
"type": "string",
"format": "date-time",
"description": "Start time. ISO 8601 timestamp accepted by the Veryfront API. The backend converts it to the unix-second format required by Grafana Cloud Tempo. Traces are kept for 30 days and one search spans at most 30 days; an older start or a wider range returns 400."
},
"required": false,
"description": "Start time. ISO 8601 timestamp accepted by the Veryfront API. The backend converts it to the unix-second format required by Grafana Cloud Tempo. Traces are kept for 30 days and one search spans at most 30 days; an older start or a wider range returns 400.",
"name": "start",
"in": "query"
},
{
"schema": {
"type": "string",
"format": "date-time",
"description": "End time. ISO 8601 timestamp accepted by the Veryfront API. The backend converts it to the unix-second format required by Grafana Cloud Tempo. Traces are kept for 30 days and one search spans at most 30 days; an older start or a wider range returns 400."
},
"required": false,
"description": "End time. ISO 8601 timestamp accepted by the Veryfront API. The backend converts it to the unix-second format required by Grafana Cloud Tempo. Traces are kept for 30 days and one search spans at most 30 days; an older start or a wider range returns 400.",
"name": "end",
"in": "query"
},
{
"schema": {
"type": "number",
"minimum": 1,
"maximum": 100,
"default": 20,
"description": "Max traces to return (default: 20, max: 100)."
},
"required": false,
"description": "Max traces to return (default: 20, max: 100).",
"name": "limit",
"in": "query"
},
{
"schema": {
"type": "string",
"maxLength": 200,
"description": "Optional OpenTelemetry service.name filter, for example veryfront-api, veryfront-studio, or veryfront-server."
},
"required": false,
"description": "Optional OpenTelemetry service.name filter, for example veryfront-api, veryfront-studio, or veryfront-server.",
"name": "service",
"in": "query"
},
{
"schema": {
"type": "string",
"enum": [
"ok",
"error",
"unset"
],
"description": "Optional Tempo status filter. Use ok, error, or unset. error matches traces with an error span of the project or without project context anywhere in the trace, as trace detail reports."
},
"required": false,
"description": "Optional Tempo status filter. Use ok, error, or unset. error matches traces with an error span of the project or without project context anywhere in the trace, as trace detail reports.",
"name": "status",
"in": "query"
},
{
"schema": {
"type": [
"number",
"null"
],
"minimum": 0,
"description": "Optional minimum trace duration in milliseconds."
},
"required": false,
"description": "Optional minimum trace duration in milliseconds.",
"name": "min_duration_ms",
"in": "query"
},
{
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Optional run ID. Returns traces with a span whose run.id, parent.run.id, or agent.run.id is this run, or that contain its runtime control-plane request."
},
"required": false,
"description": "Optional run ID. Returns traces with a span whose run.id, parent.run.id, or agent.run.id is this run, or that contain its runtime control-plane request.",
"name": "run_id",
"in": "query"
},
{
"schema": {
"type": "string",
"enum": [
"timestamp",
"duration",
"status",
"service"
],
"default": "timestamp",
"description": "Field to order the returned traces by. Defaults to timestamp; ties break by trace ID ascending. MCP and GraphQL preserve the search's newest-first nanosecond order when both sort controls are omitted."
},
"required": false,
"description": "Field to order the returned traces by. Defaults to timestamp; ties break by trace ID ascending. MCP and GraphQL preserve the search's newest-first nanosecond order when both sort controls are omitted.",
"name": "sort_by",
"in": "query"
},
{
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"default": "desc",
"description": "Sort direction. Defaults to desc."
},
"required": false,
"description": "Sort direction. Defaults to desc.",
"name": "sort_order",
"in": "query"
}
]Responses
200
Compact, project-scoped summaries of recent Grafana Cloud Tempo traces
{
"description": "Compact, project-scoped summaries of recent Grafana Cloud Tempo traces",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"traces": {
"type": "array",
"items": {
"type": "object",
"properties": {
"trace_id": {
"type": "string"
},
"root_span_name": {
"type": "string"
},
"root_service": {
"type": "string"
},
"started_at": {
"type": "string"
},
"duration_ms": {
"type": "number"
},
"status": {
"type": "string",
"enum": [
"ok",
"error",
"unset",
"unknown"
]
},
"span_count": {
"type": "number"
},
"services": {
"type": "array",
"items": {
"type": "string"
}
},
"project_id": {
"type": "string"
},
"project_slug": {
"type": "string"
},
"environment": {
"type": "string"
},
"host": {
"type": "string"
}
},
"required": [
"trace_id",
"root_span_name",
"root_service",
"started_at",
"duration_ms",
"status",
"span_count",
"services",
"project_id"
]
}
},
"stats": {
"type": "object",
"properties": {
"query_time_ms": {
"type": "number"
}
},
"required": [
"query_time_ms"
]
}
},
"required": [
"traces",
"stats"
]
}
}
}
}400
Invalid trace query parameters, including a time range beyond retention
{
"description": "Invalid trace query parameters, including a time range beyond retention",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
}401
Unauthorized
{
"description": "Unauthorized",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
}403
Forbidden, project.logs.read capability required
{
"description": "Forbidden, project.logs.read capability required",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
}404
Project not found
{
"description": "Project not found",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
}429
Rate limit exceeded
{
"description": "Rate limit exceeded",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
}502
External trace provider error from Grafana Cloud Tempo.
{
"description": "External trace provider error from Grafana Cloud Tempo.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
}503
Trace service unavailable or Grafana Cloud Tempo read path is not configured.
{
"description": "Trace service unavailable or Grafana Cloud Tempo read path is not configured.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
}Referenced contracts
components/schemas/Problem
{
"type": "object",
"properties": {
"cause": {
"type": "string",
"enum": [
"schedule_concurrency_forbidden",
"schedule_fire_in_progress",
"schedule_run_limit_reached"
],
"description": "Schedule admission refusal."
},
"idempotency": {
"type": "object",
"properties": {
"state": {
"type": "string",
"enum": [
"in_progress",
"payload_mismatch",
"outcome_unknown"
]
},
"operation": {
"type": "string",
"minLength": 1
},
"retryable": {
"type": "boolean"
},
"retry_after_seconds": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"expires_at": {
"type": [
"string",
"null"
]
},
"recovery": {
"type": "object",
"properties": {
"available": {
"type": "boolean"
},
"description": {
"type": "string"
},
"resource_url": {
"type": "string"
}
},
"required": [
"available",
"description"
]
}
},
"required": [
"state",
"operation",
"retryable",
"retry_after_seconds",
"expires_at"
],
"description": "Replay status, retry timing, and recovery lookup."
},
"type": {
"type": "string",
"description": "URI reference identifying the problem type",
"example": "https://api.veryfront.com/errors/validation-failed"
},
"title": {
"type": "string",
"description": "Short human-readable summary of the problem",
"example": "Validation Failed"
},
"status": {
"type": "integer",
"minimum": 100,
"maximum": 599,
"description": "HTTP status code",
"example": 400
},
"code": {
"type": "string",
"description": "Stable machine-readable error code",
"example": "RUN_INVALID_INPUT"
},
"detail": {
"type": "string",
"description": "Human-readable explanation specific to this occurrence",
"example": "The 'email' field must be a valid email address"
},
"instance": {
"type": "string",
"description": "URI reference identifying the specific occurrence",
"example": "/projects/my-project/members"
},
"slug": {
"type": "string",
"description": "Stable identifier for the problem type",
"example": "validation-failed"
},
"category": {
"type": "string",
"enum": [
"AUTH",
"RESOURCE",
"VALIDATION",
"DATABASE",
"SUBSCRIPTION",
"INTEGRATION",
"INTERNAL"
],
"description": "API error category",
"example": "VALIDATION"
},
"suggestion": {
"type": "string",
"description": "Suggested action to resolve the problem",
"example": "Check the request body and query parameters against the API documentation."
},
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"field": {
"type": "string",
"description": "Field path that caused the error",
"example": "email"
},
"message": {
"type": "string",
"description": "Error message for this field",
"example": "Invalid email format"
},
"code": {
"type": "string",
"description": "Error code for this field",
"example": "INVALID_FORMAT"
}
},
"required": [
"field",
"message"
]
},
"description": "Detailed field-level errors for validation failures"
}
},
"required": [
"type",
"title",
"status"
]
}Operation contract
{
"operationId": "listProjectTraces",
"tags": [
"observability/Traces/Trace Search"
],
"summary": "Query traces",
"description": "Query project traces. Requires project.logs.read.",
"parameters": [
{
"schema": {
"type": "string",
"description": "Project slug or UUID. The resolved project is used to scope all trace reads server-side."
},
"required": true,
"name": "project_reference",
"in": "path"
},
{
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[A-Za-z0-9._-]+$",
"description": "Exact runtime environment tag, for example preview or production. Untagged telemetry is excluded."
},
"required": false,
"description": "Exact runtime environment tag, for example preview or production. Untagged telemetry is excluded.",
"name": "environment",
"in": "query"
},
{
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 253,
"pattern": "^[A-Za-z0-9.-]+(?::[0-9]+)?$",
"description": "Exact request host (without scheme or path), for example demo.preview.veryfront.com. Untagged telemetry is excluded."
},
"required": false,
"description": "Exact request host (without scheme or path), for example demo.preview.veryfront.com. Untagged telemetry is excluded.",
"name": "host",
"in": "query"
},
{
"schema": {
"type": "string",
"format": "date-time",
"description": "Start time. ISO 8601 timestamp accepted by the Veryfront API. The backend converts it to the unix-second format required by Grafana Cloud Tempo. Traces are kept for 30 days and one search spans at most 30 days; an older start or a wider range returns 400."
},
"required": false,
"description": "Start time. ISO 8601 timestamp accepted by the Veryfront API. The backend converts it to the unix-second format required by Grafana Cloud Tempo. Traces are kept for 30 days and one search spans at most 30 days; an older start or a wider range returns 400.",
"name": "start",
"in": "query"
},
{
"schema": {
"type": "string",
"format": "date-time",
"description": "End time. ISO 8601 timestamp accepted by the Veryfront API. The backend converts it to the unix-second format required by Grafana Cloud Tempo. Traces are kept for 30 days and one search spans at most 30 days; an older start or a wider range returns 400."
},
"required": false,
"description": "End time. ISO 8601 timestamp accepted by the Veryfront API. The backend converts it to the unix-second format required by Grafana Cloud Tempo. Traces are kept for 30 days and one search spans at most 30 days; an older start or a wider range returns 400.",
"name": "end",
"in": "query"
},
{
"schema": {
"type": "number",
"minimum": 1,
"maximum": 100,
"default": 20,
"description": "Max traces to return (default: 20, max: 100)."
},
"required": false,
"description": "Max traces to return (default: 20, max: 100).",
"name": "limit",
"in": "query"
},
{
"schema": {
"type": "string",
"maxLength": 200,
"description": "Optional OpenTelemetry service.name filter, for example veryfront-api, veryfront-studio, or veryfront-server."
},
"required": false,
"description": "Optional OpenTelemetry service.name filter, for example veryfront-api, veryfront-studio, or veryfront-server.",
"name": "service",
"in": "query"
},
{
"schema": {
"type": "string",
"enum": [
"ok",
"error",
"unset"
],
"description": "Optional Tempo status filter. Use ok, error, or unset. error matches traces with an error span of the project or without project context anywhere in the trace, as trace detail reports."
},
"required": false,
"description": "Optional Tempo status filter. Use ok, error, or unset. error matches traces with an error span of the project or without project context anywhere in the trace, as trace detail reports.",
"name": "status",
"in": "query"
},
{
"schema": {
"type": [
"number",
"null"
],
"minimum": 0,
"description": "Optional minimum trace duration in milliseconds."
},
"required": false,
"description": "Optional minimum trace duration in milliseconds.",
"name": "min_duration_ms",
"in": "query"
},
{
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Optional run ID. Returns traces with a span whose run.id, parent.run.id, or agent.run.id is this run, or that contain its runtime control-plane request."
},
"required": false,
"description": "Optional run ID. Returns traces with a span whose run.id, parent.run.id, or agent.run.id is this run, or that contain its runtime control-plane request.",
"name": "run_id",
"in": "query"
},
{
"schema": {
"type": "string",
"enum": [
"timestamp",
"duration",
"status",
"service"
],
"default": "timestamp",
"description": "Field to order the returned traces by. Defaults to timestamp; ties break by trace ID ascending. MCP and GraphQL preserve the search's newest-first nanosecond order when both sort controls are omitted."
},
"required": false,
"description": "Field to order the returned traces by. Defaults to timestamp; ties break by trace ID ascending. MCP and GraphQL preserve the search's newest-first nanosecond order when both sort controls are omitted.",
"name": "sort_by",
"in": "query"
},
{
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"default": "desc",
"description": "Sort direction. Defaults to desc."
},
"required": false,
"description": "Sort direction. Defaults to desc.",
"name": "sort_order",
"in": "query"
}
],
"responses": {
"200": {
"description": "Compact, project-scoped summaries of recent Grafana Cloud Tempo traces",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"traces": {
"type": "array",
"items": {
"type": "object",
"properties": {
"trace_id": {
"type": "string"
},
"root_span_name": {
"type": "string"
},
"root_service": {
"type": "string"
},
"started_at": {
"type": "string"
},
"duration_ms": {
"type": "number"
},
"status": {
"type": "string",
"enum": [
"ok",
"error",
"unset",
"unknown"
]
},
"span_count": {
"type": "number"
},
"services": {
"type": "array",
"items": {
"type": "string"
}
},
"project_id": {
"type": "string"
},
"project_slug": {
"type": "string"
},
"environment": {
"type": "string"
},
"host": {
"type": "string"
}
},
"required": [
"trace_id",
"root_span_name",
"root_service",
"started_at",
"duration_ms",
"status",
"span_count",
"services",
"project_id"
]
}
},
"stats": {
"type": "object",
"properties": {
"query_time_ms": {
"type": "number"
}
},
"required": [
"query_time_ms"
]
}
},
"required": [
"traces",
"stats"
]
}
}
}
},
"400": {
"description": "Invalid trace query parameters, including a time range beyond retention",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"403": {
"description": "Forbidden, project.logs.read capability required",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"404": {
"description": "Project not found",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"429": {
"description": "Rate limit exceeded",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"502": {
"description": "External trace provider error from Grafana Cloud Tempo.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"503": {
"description": "Trace service unavailable or Grafana Cloud Tempo read path is not configured.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
}
},
"x-documentation-source-tag": "Project traces",
"x-canonical-documentation": {
"domain": "observability",
"resource": "Traces",
"subgroup": "Trace Search",
"name": "Query traces",
"description": "Query project traces. Requires project.logs.read.",
"operationId": "listProjectTraces"
},
"x-mint": {
"href": "/cloud/rest/api-reference/observability-traces-trace-search/query-traces"
}
}