Summarize run events

curl --request GET \
  --url https://api.veryfront.com/runs/{run_id}/events/summary \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.veryfront.com/runs/{run_id}/events/summary', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.veryfront.com/runs/{run_id}/events/summary",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.veryfront.com/runs/{run_id}/events/summary"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.veryfront.com/runs/{run_id}/events/summary")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "run_id": "<string>",
  "total": 1,
  "error_count": 1,
  "first_event_id": 1,
  "last_event_id": 1,
  "first_event_at": "2023-11-07T05:31:56Z",
  "last_event_at": "2023-11-07T05:31:56Z",
  "by_event_class": {
    "fact": 1,
    "delta": 1
  },
  "by_event_type": [
    {
      "event_type": "<string>",
      "event_class": "fact",
      "count": 1,
      "error_count": 1
    }
  ],
  "buckets": [
    {
      "start": "2023-11-07T05:31:56Z",
      "end": "2023-11-07T05:31:56Z",
      "count": 1,
      "error_count": 1
    }
  ]
}

{
  "type": "https://api.veryfront.com/errors/validation-failed",
  "title": "Validation Failed",
  "status": 400,
  "idempotency": {
    "state": "in_progress",
    "operation": "<string>",
    "retryable": true,
    "retry_after_seconds": 1,
    "expires_at": "<string>",
    "recovery": {
      "available": true,
      "description": "<string>",
      "resource_url": "<string>"
    }
  },
  "code": "RUN_INVALID_INPUT",
  "detail": "The 'email' field must be a valid email address",
  "instance": "/projects/my-project/members",
  "slug": "validation-failed",
  "category": "VALIDATION",
  "suggestion": "Check the request body and query parameters against the API documentation.",
  "errors": [
    {
      "field": "email",
      "message": "Invalid email format",
      "code": "INVALID_FORMAT"
    }
  ]
}

{
  "type": "https://api.veryfront.com/errors/validation-failed",
  "title": "Validation Failed",
  "status": 400,
  "idempotency": {
    "state": "in_progress",
    "operation": "<string>",
    "retryable": true,
    "retry_after_seconds": 1,
    "expires_at": "<string>",
    "recovery": {
      "available": true,
      "description": "<string>",
      "resource_url": "<string>"
    }
  },
  "code": "RUN_INVALID_INPUT",
  "detail": "The 'email' field must be a valid email address",
  "instance": "/projects/my-project/members",
  "slug": "validation-failed",
  "category": "VALIDATION",
  "suggestion": "Check the request body and query parameters against the API documentation.",
  "errors": [
    {
      "field": "email",
      "message": "Invalid email format",
      "code": "INVALID_FORMAT"
    }
  ]
}

{
  "type": "https://api.veryfront.com/errors/validation-failed",
  "title": "Validation Failed",
  "status": 400,
  "idempotency": {
    "state": "in_progress",
    "operation": "<string>",
    "retryable": true,
    "retry_after_seconds": 1,
    "expires_at": "<string>",
    "recovery": {
      "available": true,
      "description": "<string>",
      "resource_url": "<string>"
    }
  },
  "code": "RUN_INVALID_INPUT",
  "detail": "The 'email' field must be a valid email address",
  "instance": "/projects/my-project/members",
  "slug": "validation-failed",
  "category": "VALIDATION",
  "suggestion": "Check the request body and query parameters against the API documentation.",
  "errors": [
    {
      "field": "email",
      "message": "Invalid email format",
      "code": "INVALID_FORMAT"
    }
  ]
}

{
  "type": "https://api.veryfront.com/errors/validation-failed",
  "title": "Validation Failed",
  "status": 400,
  "idempotency": {
    "state": "in_progress",
    "operation": "<string>",
    "retryable": true,
    "retry_after_seconds": 1,
    "expires_at": "<string>",
    "recovery": {
      "available": true,
      "description": "<string>",
      "resource_url": "<string>"
    }
  },
  "code": "RUN_INVALID_INPUT",
  "detail": "The 'email' field must be a valid email address",
  "instance": "/projects/my-project/members",
  "slug": "validation-failed",
  "category": "VALIDATION",
  "suggestion": "Check the request body and query parameters against the API documentation.",
  "errors": [
    {
      "field": "email",
      "message": "Invalid email format",
      "code": "INVALID_FORMAT"
    }
  ]
}

{
  "type": "https://api.veryfront.com/errors/validation-failed",
  "title": "Validation Failed",
  "status": 400,
  "idempotency": {
    "state": "in_progress",
    "operation": "<string>",
    "retryable": true,
    "retry_after_seconds": 1,
    "expires_at": "<string>",
    "recovery": {
      "available": true,
      "description": "<string>",
      "resource_url": "<string>"
    }
  },
  "code": "RUN_INVALID_INPUT",
  "detail": "The 'email' field must be a valid email address",
  "instance": "/projects/my-project/members",
  "slug": "validation-failed",
  "category": "VALIDATION",
  "suggestion": "Check the request body and query parameters against the API documentation.",
  "errors": [
    {
      "field": "email",
      "message": "Invalid email format",
      "code": "INVALID_FORMAT"
    }
  ]
}

Summarize run events

Counts events without returning their payloads. The response includes totals, error counts, first and last event IDs, timestamps, counts by event class and type, and a time histogram.

Event-type counts use canonical names, including normalized legacy names. Results are ordered by count descending, then by name. Timestamps use whole milliseconds.

Histogram: buckets accepts 1-500 slices and defaults to 60. Slices cover [first_event_at, last_event_at + 1 ms), use half-open [start, end) boundaries, and differ in width by at most 1 ms. Each event belongs to one slice. A slice’s boundaries can be passed directly to the event-list endpoint.

The slice count cannot exceed the time span in milliseconds. A 10 ms span therefore has at most 10 slices. When no events match, buckets is empty.

Filters: event_class, event_type, is_error, start, end, span_id, turn_id, and search use the same values and semantics as GET /runs/{run_id}/events. Filters apply to every aggregate. With include_descendants=true, the summary counts the same runs as the event list.

Filtering by search, span_id, or turn_id checks each candidate event’s caller-visible payload and envelope. These queries scan candidate rows rather than using database-only aggregation.

Limits: This endpoint does not paginate. It rejects cursor, sort_order, limit, and the list-only errors_only parameter. Viewer access is sufficient. Responses are private and must not be cached (no-store).

GET

runs

{run_id}

events

summary

Summarize run events

curl --request GET \
  --url https://api.veryfront.com/runs/{run_id}/events/summary \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.veryfront.com/runs/{run_id}/events/summary', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.veryfront.com/runs/{run_id}/events/summary",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.veryfront.com/runs/{run_id}/events/summary"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.veryfront.com/runs/{run_id}/events/summary")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "run_id": "<string>",
  "total": 1,
  "error_count": 1,
  "first_event_id": 1,
  "last_event_id": 1,
  "first_event_at": "2023-11-07T05:31:56Z",
  "last_event_at": "2023-11-07T05:31:56Z",
  "by_event_class": {
    "fact": 1,
    "delta": 1
  },
  "by_event_type": [
    {
      "event_type": "<string>",
      "event_class": "fact",
      "count": 1,
      "error_count": 1
    }
  ],
  "buckets": [
    {
      "start": "2023-11-07T05:31:56Z",
      "end": "2023-11-07T05:31:56Z",
      "count": 1,
      "error_count": 1
    }
  ]
}

{
  "type": "https://api.veryfront.com/errors/validation-failed",
  "title": "Validation Failed",
  "status": 400,
  "idempotency": {
    "state": "in_progress",
    "operation": "<string>",
    "retryable": true,
    "retry_after_seconds": 1,
    "expires_at": "<string>",
    "recovery": {
      "available": true,
      "description": "<string>",
      "resource_url": "<string>"
    }
  },
  "code": "RUN_INVALID_INPUT",
  "detail": "The 'email' field must be a valid email address",
  "instance": "/projects/my-project/members",
  "slug": "validation-failed",
  "category": "VALIDATION",
  "suggestion": "Check the request body and query parameters against the API documentation.",
  "errors": [
    {
      "field": "email",
      "message": "Invalid email format",
      "code": "INVALID_FORMAT"
    }
  ]
}

{
  "type": "https://api.veryfront.com/errors/validation-failed",
  "title": "Validation Failed",
  "status": 400,
  "idempotency": {
    "state": "in_progress",
    "operation": "<string>",
    "retryable": true,
    "retry_after_seconds": 1,
    "expires_at": "<string>",
    "recovery": {
      "available": true,
      "description": "<string>",
      "resource_url": "<string>"
    }
  },
  "code": "RUN_INVALID_INPUT",
  "detail": "The 'email' field must be a valid email address",
  "instance": "/projects/my-project/members",
  "slug": "validation-failed",
  "category": "VALIDATION",
  "suggestion": "Check the request body and query parameters against the API documentation.",
  "errors": [
    {
      "field": "email",
      "message": "Invalid email format",
      "code": "INVALID_FORMAT"
    }
  ]
}

{
  "type": "https://api.veryfront.com/errors/validation-failed",
  "title": "Validation Failed",
  "status": 400,
  "idempotency": {
    "state": "in_progress",
    "operation": "<string>",
    "retryable": true,
    "retry_after_seconds": 1,
    "expires_at": "<string>",
    "recovery": {
      "available": true,
      "description": "<string>",
      "resource_url": "<string>"
    }
  },
  "code": "RUN_INVALID_INPUT",
  "detail": "The 'email' field must be a valid email address",
  "instance": "/projects/my-project/members",
  "slug": "validation-failed",
  "category": "VALIDATION",
  "suggestion": "Check the request body and query parameters against the API documentation.",
  "errors": [
    {
      "field": "email",
      "message": "Invalid email format",
      "code": "INVALID_FORMAT"
    }
  ]
}

{
  "type": "https://api.veryfront.com/errors/validation-failed",
  "title": "Validation Failed",
  "status": 400,
  "idempotency": {
    "state": "in_progress",
    "operation": "<string>",
    "retryable": true,
    "retry_after_seconds": 1,
    "expires_at": "<string>",
    "recovery": {
      "available": true,
      "description": "<string>",
      "resource_url": "<string>"
    }
  },
  "code": "RUN_INVALID_INPUT",
  "detail": "The 'email' field must be a valid email address",
  "instance": "/projects/my-project/members",
  "slug": "validation-failed",
  "category": "VALIDATION",
  "suggestion": "Check the request body and query parameters against the API documentation.",
  "errors": [
    {
      "field": "email",
      "message": "Invalid email format",
      "code": "INVALID_FORMAT"
    }
  ]
}

{
  "type": "https://api.veryfront.com/errors/validation-failed",
  "title": "Validation Failed",
  "status": 400,
  "idempotency": {
    "state": "in_progress",
    "operation": "<string>",
    "retryable": true,
    "retry_after_seconds": 1,
    "expires_at": "<string>",
    "recovery": {
      "available": true,
      "description": "<string>",
      "resource_url": "<string>"
    }
  },
  "code": "RUN_INVALID_INPUT",
  "detail": "The 'email' field must be a valid email address",
  "instance": "/projects/my-project/members",
  "slug": "validation-failed",
  "category": "VALIDATION",
  "suggestion": "Check the request body and query parameters against the API documentation.",
  "errors": [
    {
      "field": "email",
      "message": "Invalid email format",
      "code": "INVALID_FORMAT"
    }
  ]
}

Authorizations

Authorization

string

header

required

Use a JWT bearer token or a Veryfront API key in the Authorization header.

Path Parameters

run_id

string

required

Minimum string length: 1

Query Parameters

buckets

integer

default:60

Number of time buckets spanning first_event_at up to 1 ms past last_event_at (1-500, default 60). Bucket boundaries are whole milliseconds and every bucket is at least 1 ms wide, so the response holds at most as many buckets as the span has milliseconds and may return fewer than requested (a 10 ms span returns at most 10).

Required range: 1 <= x <= 500

event_class

enum<string>

Event class to include: fact for state changes or delta for streaming fragments. If omitted, returns both.

Available options:

fact,

delta

event_type

Only events of these canonical types (comma-separated, repeatable, at most 32). A legacy-spelled stored row matches under the type it is served as.

is_error

enum<string>

If true, returns only events with is_error: true. If false, returns other events. If omitted, returns both.

Available options:

true,

false

start

string<date-time>

Only events created at or after this instant (ISO 8601 with a UTC offset, inclusive). A summary bucket start can be sent as is.

end

string<date-time>

Only events created before this instant (ISO 8601 with a UTC offset, exclusive). Must be later than start. A summary bucket end can be sent as is.

span_id

string

Only events whose envelope span_id, as served to the caller, is exactly this value (tool:, message:, step:, input_request:, run:, with a non-empty ).

Minimum string length: 1

turn_id

string

Only events whose envelope turn_id, as served to the caller, is exactly this value (message:, with a non-empty ).

Minimum string length: 1

string

Case-insensitive substring of the event payload JSON as served to the caller (1-200 characters after trimming, matched literally).

Required string length: 1 - 200

include_descendants

enum<string>

default:false

If true, includes events from readable descendant runs, up to 16 generations. Results share one event_id order and cursor. Each event retains its run_id and the payload visibility permitted for that run. Runs the caller cannot read are excluded. Defaults to false.

If at least one descendant is included, task or workflow runs without stored events do not contribute synthetic lifecycle events. Event IDs are allocated before commit. During active writes, ascending pagination can pass an ID that another run commits later.

Available options:

true,

false

Response

Run event summary

run_id

string

required

Minimum string length: 1

total

integer

required

Required range: x >= 0

error_count

integer

required

Required range: x >= 0

first_event_id

integer | null

required

Required range: x >= 0

last_event_id

integer | null

required

Required range: x >= 0

first_event_at

string<date-time> | null

required

last_event_at

string<date-time> | null

required

by_event_class

object

required

Show child attributes

by_event_type

object[]

required

Show child attributes

buckets

object[]

required

Half-open time buckets [start, end) covering first_event_at through last_event_at + 1 ms. Boundaries use whole milliseconds; widths differ by at most 1 ms. Boundaries can be passed directly as the event-list start and end filters. The bucket count cannot exceed the span in milliseconds. Empty if no events match.

Show child attributes

Get started

APIs

REST API

GraphQL API

MCP API

Summarize run events

Authorizations

Path Parameters

Query Parameters

Response