Function Logs

View historical and live execution logs for your functions.

Read runtime and deployment logs with a platform token belonging to the project owner or a project access token. A read_only project token is sufficient. Project end-user sessions, anon keys, and service keys do not grant log access. Keep project tokens on your server and rotate them through project token management.

For SDK examples, see JavaScript, Python, and Ruby.

Runtime Logs

Use this endpoint for paginated historical runtime logs and text or structured-field search:

POST /projects/{id}/logs/search
Authorization: Bearer PLATFORM_TOKEN
Content-Type: application/json

Set resource.type to function. Omit resource.ids to return logs across all functions in the project, or include one or more function IDs to return logs for selected functions. A durable function is read the same way, by its own ID; its runtime logs cover every execution, including what each resume logged again. The q field is optional; leave it blank or omit it to list stored logs using structured filters only.

curl -X POST "https://api.volcano.dev/projects/PROJECT_ID/logs/search" \
  -H "Authorization: Bearer PLATFORM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"resource":{"type":"function","ids":["FUNC_ID"]}}'

Response:

{
  "data": [
    {
      "id": "log/us-east-1/01HKG3W9M0A5V7R2J6Z0Q6Y4S9",
      "timestamp": "2024-01-01T12:00:00Z",
      "level": "info",
      "body": {
        "message": "User logged in",
        "user_id": "usr_123"
      },
      "resource": {
        "type": "function",
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "login"
      },
      "region": "us-east-1"
    }
  ],
  "limit": 100,
  "has_more": true,
  "next_cursor": "eyJwayI6..."
}

Internal platform runtime logs are filtered out; only application logs emitted by deployed functions are returned.

Historical log rows identify the owning function or frontend with a required resource object. Deployment log rows include a deployment object when available.

Filtering

Supported request body fields:

Field	Description
`resource.type`	Required. Use `function`.
`resource.ids`	Optional function IDs. Omit or pass an empty array to search all functions in the project.
`q`	Optional query. Unqualified terms search the body. Supports quoted text, implicit `AND`, `AND`/`OR`/`NOT`, parentheses, and the fields `body`, `level`, `region`, `invocation.id`, `resource.id`, and `resource.name`. The resource-name aliases `function`, `frontend`, and `database` are also supported.
`limit`	Max records to return. Default `100`, max `1000`.
`cursor`	Opaque cursor from the previous response.
`start_time`	Inclusive lower bound as an RFC3339 timestamp.
`end_time`	Inclusive upper bound as an RFC3339 timestamp.

# Find "checkout_failed" in warn and error logs in one region
curl -X POST "https://api.volcano.dev/projects/PROJECT_ID/logs/search" \
  -H "Authorization: Bearer PLATFORM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"resource":{"type":"function","ids":["FUNC_ID"]},"q":"level:(warn OR error) region:us-east-1 body:checkout_failed","start_time":"2024-01-01T12:00:00Z","end_time":"2024-01-01T13:00:00Z"}'

Pagination

When has_more is true, pass the response next_cursor back as the cursor field on the next request with the same filters.

curl -X POST ".../logs/search" \
  -H "Authorization: Bearer PLATFORM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"resource":{"type":"function"},"limit":100}'

curl -X POST ".../logs/search" \
  -H "Authorization: Bearer PLATFORM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"resource":{"type":"function"},"limit":100,"cursor":"eyJwayI6..."}'

Live Streaming

Use the stream endpoint to live-tail runtime or deployment logs:

POST /projects/{id}/logs/stream
Authorization: Bearer PLATFORM_TOKEN
Content-Type: application/json
Accept: text/event-stream

The request body supports resource, q, start_time, and limit. The q field uses the same syntax as search requests. Do not send cursor or end_time; use /logs/search for range backfills.

curl -N -X POST "https://api.volcano.dev/projects/PROJECT_ID/logs/stream" \
  -H "Authorization: Bearer PLATFORM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"resource":{"type":"function","ids":["FUNC_ID"]},"q":"level:error"}'

Each log event is sent as Server-Sent Events:

id: STREAM_CURSOR
event: log
data: {"id":"LOG_EVENT_ID","timestamp":"2024-01-01T12:00:00Z","level":"info","body":"User logged in","resource":{"type":"function","id":"FUNC_ID","name":"login"},"region":"us-east-1"}

The SSE id field is an opaque stream cursor. To reconnect without replaying recent events, send the most recent id as the Last-Event-ID header or last_event_id query parameter. The log event's stable ID remains in data.id.

The cursor is bound to the request body: resource, q, start_time, and limit must match the original request when reconnecting. Resuming with a changed body returns 400 — open a new stream (without a cursor) for the new selector instead.

This is a live tail, not a gap-free backfill. On connect (or reconnect) the server delivers at most limit of the most recent matching events from the cursor position and then follows new events. If a stream stays disconnected long enough for more than limit events to accumulate, the older events in that gap are not replayed — use /logs/search to backfill a specific time range.

The stream sends : keepalive comments while idle. If a transient read fails after the stream is open, the server emits an event: warning payload and continues retrying. The warning's error field carries a safe message; internal failures are reported generically and logged server-side.

Deployment Logs

Deployment build logs use the same project log search endpoint. Add a resource.deployments.ids selector to read one or more deployments for the selected function resources. New function and frontend builds show dependency installation, project build and syntax-check output, concise progress, and actionable errors. Platform setup, packaging, and publishing diagnostics stay in internal operator logs. Existing historical logs are unchanged.

POST /projects/{id}/logs/search
Authorization: Bearer PLATFORM_TOKEN

curl -X POST "https://api.volcano.dev/projects/PROJECT_ID/logs/search" \
  -H "Authorization: Bearer PLATFORM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"resource":{"type":"function","ids":["FUNC_ID"],"deployments":{"ids":["DEPLOYMENT_ID"]}},"limit":100}'

Use the same selector with /logs/stream to live-tail deployment logs.

Deployment log rows include deployment context:

{
  "resource": {
    "type": "function",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "login"
  },
  "deployment": {
    "id": "8c6c7c2e-e3ff-42a5-ae4d-650ef9b45746"
  }
}

Logging Best Practices

Use structured logging so important fields can be indexed:

console.log(JSON.stringify({
  level: 'info',
  action: 'user_login',
  user_id: user.id,
  timestamp: new Date().toISOString()
}));

Use consistent log levels:

console.log('INFO:', ...);
console.error('ERROR:', ...);
console.warn('WARN:', ...);