Query traces

http
GET /projects/{project_reference}/traces

Query project traces. Requires project.logs.read.

Servers

json
[
  {
    "url": "https://api.veryfront.com"
  }
]

Authentication

json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyAuth": []
  }
]
json
{
  "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

NameLocationRequiredDescription
project_referencepathYes
environmentqueryNoExact runtime environment tag, for example preview or production. Untagged telemetry is excluded.
hostqueryNoExact request host (without scheme or path), for example demo.preview.veryfront.com. Untagged telemetry is excluded.
startqueryNoStart 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.
endqueryNoEnd 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.
limitqueryNoMax traces to return (default: 20, max: 100).
servicequeryNoOptional OpenTelemetry service.name filter, for example veryfront-api, veryfront-studio, or veryfront-server.
statusqueryNoOptional 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.
min_duration_msqueryNoOptional minimum trace duration in milliseconds.
run_idqueryNoOptional 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.
sort_byqueryNoField 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.
sort_orderqueryNoSort direction. Defaults to desc.

Parameter contracts

json
[
  {
    "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

json
{
  "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

json
{
  "description": "Invalid trace query parameters, including a time range beyond retention",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/Problem"
      }
    }
  }
}

401

Unauthorized

json
{
  "description": "Unauthorized",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/Problem"
      }
    }
  }
}

403

Forbidden, project.logs.read capability required

json
{
  "description": "Forbidden, project.logs.read capability required",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/Problem"
      }
    }
  }
}

404

Project not found

json
{
  "description": "Project not found",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/Problem"
      }
    }
  }
}

429

Rate limit exceeded

json
{
  "description": "Rate limit exceeded",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/Problem"
      }
    }
  }
}

502

External trace provider error from Grafana Cloud Tempo.

json
{
  "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.

json
{
  "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

json
{
  "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

json
{
  "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"
  }
}