Logs

Function logs are currently in early beta. The API surface may change as development continues.

The Gram Logs API provides an interface for retrieving structured logs from function executions. This allows monitoring and debugging of deployed functions by accessing their stdout and stderr output programmatically.

Endpoint


GET https://app.getgram.ai/rpc/logs.listToolExecutionLogs

Authentication

Requests must include authentication credentials in headers:

Gram-Key: Your API key (can be either Consumer or Producer scoped)
Gram-Project: The project identifier (slug)

Query parameters

Parameter	Type	Description
`ts_start`	string	Start timestamp in RFC3339 format (defaults to Unix epoch)
`ts_end`	string	End timestamp in RFC3339 format (defaults to year 2100)
`deployment_id`	string	Filter by deployment UUID
`function_id`	string	Filter by function UUID
`instance`	string	Filter by instance identifier
`level`	string	Filter by log level: `debug`, `info`, `warn`, or `error`
`source`	string	Filter by source: (`server` or `function`)
`cursor`	string	Cursor ID for pagination (UUID format)
`per_page`	number	Items per page (1-100, default: 20)
`sort`	string	Sort order: `asc` or `desc` (default: `desc`)
`direction`	string	Pagination direction: `next` or `prev` (default: `next`)

Response structure

The API returns a JSON object with the following structure:


{
  "logs": [
    {
      "id": "uuid",
      "timestamp": "2025-12-15T10:30:00Z",
      "instance": "instance-identifier",
      "level": "info",
      "source": "server",
      "raw_log": "raw log message",
      "message": "parsed log message",
      "attributes": "{}",
      "project_id": "project-uuid",
      "deployment_id": "deployment-uuid",
      "function_id": "function-uuid"
    }
  ],
  "pagination": {
    "per_page": 20,
    "has_next_page": true,
    "next_page_cursor": "uuid"
  }
}

Log entry fields

Each log entry includes:

id: Unique identifier for the log entry (UUID)
timestamp: When the log was generated (RFC3339 format)
instance: Instance identifier where the function executed
level: Log severity level (debug, info, warn, error)
source: The source of the log (server or function)
raw_log: Unprocessed log message as emitted by the function
message: Parsed or formatted log message (may be null)
attributes: JSON-encoded additional metadata
project_id: Associated project UUID
deployment_id: Associated deployment UUID
function_id: Associated function UUID

Pagination

Results are paginated using cursor-based pagination:

Set per_page to control page size (maximum 100)
Use sort to control ordering (newest first with desc or oldest first with asc)
Check pagination.has_next_page to determine if more results exist
Use pagination.next_page_cursor value as the cursor parameter for the next request

The cursor is a UUID that encodes the position in the result set. Always use the cursor value from the previous response rather than constructing your own.

Example usage

Basic query

Retrieve the most recent logs for a project:


curl -X GET "https://app.getgram.ai/rpc/logs.listToolExecutionLogs?per_page=20&sort=desc" \
  -H "Gram-Key: your-api-key" \
  -H "Gram-Project: your-project-slug"

Filter by function

Get logs for a specific function:


curl -X GET "https://app.getgram.ai/rpc/logs.listToolExecutionLogs?function_id=FUNCTION_UUID&per_page=50" \
  -H "Gram-Key: your-api-key" \
  -H "Gram-Project: your-project-slug"

Filter by level

Retrieve only error logs:


curl -X GET "https://app.getgram.ai/rpc/logs.listToolExecutionLogs?level=error&per_page=100" \
  -H "Gram-Key: your-api-key" \
  -H "Gram-Project: your-project-slug"

Time range query

Get logs within a specific time window:


curl -X GET "https://app.getgram.ai/rpc/logs.listToolExecutionLogs?ts_start=2025-12-01T00:00:00Z&ts_end=2025-12-15T23:59:59Z" \
  -H "Gram-Key: your-api-key" \
  -H "Gram-Project: your-project-slug"

Paginated query

Fetch the next page of results:


curl -X GET "https://app.getgram.ai/rpc/logs.listToolExecutionLogs?cursor=CURSOR_UUID&per_page=20" \
  -H "Gram-Key: your-api-key" \
  -H "Gram-Project: your-project-slug"

Error handling

The API returns standard HTTP status codes:

200: Success
400: Bad request (invalid parameters)
401: Unauthorized (missing or invalid credentials)
403: Forbidden (insufficient permissions)
500: Internal server error

Use cases

Debugging function execution

Query logs by function ID to troubleshoot issues:


curl -X GET "https://app.getgram.ai/rpc/logs.listToolExecutionLogs?function_id=FUNCTION_UUID&level=error" \
  -H "Gram-Key: your-api-key" \
  -H "Gram-Project: your-project-slug"

Monitoring deployment health

Filter logs by deployment to monitor a specific release:


curl -X GET "https://app.getgram.ai/rpc/logs.listToolExecutionLogs?deployment_id=DEPLOYMENT_UUID&source=function" \
  -H "Gram-Key: your-api-key" \
  -H "Gram-Project: your-project-slug"

Aggregating metrics

Retrieve logs over a time range for analysis:


curl -X GET "https://app.getgram.ai/rpc/logs.listToolExecutionLogs?ts_start=2025-12-01T00:00:00Z&ts_end=2025-12-15T23:59:59Z&per_page=100" \
  -H "Gram-Key: your-api-key" \
  -H "Gram-Project: your-project-slug"

Last updated on December 12, 2025