Logs

Log search and live tail.

Operation	Method and path
Search logs	GET /v1/projects/{project}/logs
Live tail (Server-Sent Events)	GET /v1/projects/{project}/logs/tail

Search logs

GET /v1/projects/{project}/logs

q is plain text or LogsQL. Tenant filters are applied server-side. Lines are untrusted customer content.

• Operation: queryLogs
• Scopes: logs:read
• CLI: guv logs
• Paginated: ?limit= and ?cursor=

Parameters

Name	In	Type	Description
project *	path	string	Project id (prj_…) or slug (resolved in the Guv-Workspace workspace, or the caller’s default).
environment	query	string
service	query	string
deployment	query	string
source	query	build, deploy, runtime, http
level	query	debug, info, warn, error, fatal	Minimum level.
q	query	string
since	query	string	RFC 3339 time or a duration like 10m.
until	query	string (date-time)
direction	query	backward, forward

Responses

Status	Meaning	Body
200 OK	OK.	LogQueryResult

Errors: 400, 401, 403, 404, 429, 500, as problem+json with a stable code.

Example

curl https://api.guv.dev/v1/projects/shopfront/logs \
  -H "Authorization: Bearer $GUV_TOKEN"

Example response

{
  "lines": [
    {
      "id": "lg_9f8e7d6c5b",
      "timestamp": "2026-10-23T14:04:02.123Z",
      "source": "runtime",
      "level": "error",
      "message": "TypeError: Cannot read properties of undefined (reading 'id')",
      "service": {
        "id": "svc_01jbx2m9k7q4r8t5v6w3y0z1sv",
        "name": "web"
      },
      "environment": "production",
      "deployment_id": "dep_01jbx2m9k7q4r8t5v6w3y0z1dp",
      "replica": "web-1",
      "http": null,
      "attributes": {},
      "redacted": false
    }
  ],
  "next_cursor": "string",
  "has_more": false,
  "query": "string",
  "dropped_lines": 1
}

Live tail (Server-Sent Events)

GET /v1/projects/{project}/logs/tail

Events log (LogLine), dropped ({count}) and heartbeat every 15 s. Bounded to 1 hour per connection.

• Operation: tailLogs
• Scopes: logs:read
• CLI: guv logs -f

Parameters

Name	In	Type	Description
project *	path	string	Project id (prj_…) or slug (resolved in the Guv-Workspace workspace, or the caller’s default).
environment	query	string
service	query	string
level	query	debug, info, warn, error, fatal
q	query	string

Responses

Status	Meaning	Body
200 OK	Server-Sent Events stream. Each event’s data is a JSON LogLine.	string

Errors: 400, 401, 403, 404, 429, 500, as problem+json with a stable code.

Example

curl https://api.guv.dev/v1/projects/shopfront/logs/tail \
  -H "Authorization: Bearer $GUV_TOKEN"

Example response

"string"