Pulse Views
A Pulse View is a saved set of benchmark runs that you read as charts and tables. The Curator RPCs find the runs you can put in a View. The View RPCs create a View, add runs to it, and read its data. The Pulse page describes the same features in the web app.
Set these environment variables for the examples:
export METRUM_API_URL="https://<control-plane-host>/api/postgrest"
export METRUM_JWT_TOKEN="<personal-access-token>"
export METRUM_ORG_ID="<org-uuid>"
How Pulse RPCs Work
| Topic | Rule |
|---|---|
| Caller | Every Pulse RPC reads your account from the token. No Pulse RPC takes p_account_id. A request without a token fails with HTTP 401. |
| Workspace | Every Pulse RPC takes p_org_id. The Curator RPCs require that you own or belong to the workspace, or are a metrum admin. |
| Eligible runs | A run is a benchmark job. A job is eligible when its status is completed or partial, its tool is shown to customers, and its project belongs to the workspace and is not a demo project. |
| Projects | Team projects (visibility org) are always eligible. A private project is eligible only when you name it in the private project parameter and you may include it. |
| Include a private project | You may include a private project when you can access it and you are its owner or creator, hold a write or owner grant on it, are the workspace owner or an admin, or are a metrum admin. |
| View owner | Only the owner of a View can change it, add runs, or check it for new runs. A workspace admin or metrum admin cannot change another owner's View. |
| Snapshot | A View never gains runs on its own. You add runs by hand. |
Permissions use the Casbin resource pulse_view. pulse_view:read belongs to
the owner, admin, member, and viewer roles. pulse_view:write belongs to the
owner, admin, and member roles.
Search
p_search splits on spaces and keeps the first 8 words of the first 200
characters. Every word must match one of these, ignoring case: project,
run, workload, scenario, tool, model, engine, machine, or status text, or the
job's UTC creation date as YYYY-MM-DD. A word also matches when it equals
the job id or the run id. A date word such as 2026-10 therefore matches by
prefix.
Date range
p_date_from and p_date_to are dates in UTC. Both ends are inclusive.
Errors
Each Pulse error message starts with a code in capitals.
| Message code | SQLSTATE | HTTP status | Cause |
|---|---|---|---|
AUTHENTICATION_REQUIRED, or Forbidden: pulse_view:... requires authentication | 42501 | 401 | No token. |
ORG_ACCESS_DENIED | 42501 | 403 | You do not belong to the workspace. |
VIEW_ACCESS_DENIED | 42501 | 403 | You cannot read the View. |
VIEW_WRITE_DENIED | 42501 | 403 | You do not own the View. |
PRIVATE_PROJECT_NOT_ALLOWED | 42501 | 403 | A job or source project is in a private project that you did not name or may not include. |
SOURCE_PROJECT_NOT_ALLOWED | 42501 | 403 | A source project is outside the workspace, a demo project, or a private project you cannot access. |
INVALID_PAGINATION, INVALID_GROUP_BY, INVALID_DATE_RANGE | 22023 | 400 | A bad paging, grouping, or date value. |
VIEW_NAME_REQUIRED, VIEW_NAME_INVALID, VIEW_DESCRIPTION_TOO_LONG, INVALID_VIEW_CONFIG, NO_JOBS_SELECTED, JOB_NOT_FOUND | 22023 | 400 | A bad View field, or a job outside the workspace. |
VIEW_NAME_DUPLICATE | 23505 | 409 | You already have a View with this name in the workspace. |
VIEW_NOT_FOUND, NO_VISIBLE_JOBS | P0002 | 500 | The View does not exist or was deleted, or you can see none of its runs. |
PostgREST returns HTTP 500 for P0002. Read the message code to tell these
cases from a server failure.
Curator RPCs
pulse_list_source_jobs
Returns one page of the runs you can put in a View, newest first. Filters combine with AND.
curl -fsS -X POST "$METRUM_API_URL/rpc/pulse_list_source_jobs" \
-H "Authorization: Bearer $METRUM_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d "{
\"p_org_id\":\"$METRUM_ORG_ID\",
\"p_tool_codes\":[\"metrumbench-llm\"],
\"p_search\":\"qwen 2026-10\",
\"p_group_by\":\"project\",
\"p_limit\":100,
\"p_offset\":0
}" | jq
| Name | Type | Required | Description |
|---|---|---|---|
p_org_id | uuid | Yes | Workspace. |
p_include_private_project_ids | integer[] | No | Private projects to include. Each must be one you may include. |
p_status_codes | text[] | No | Keep these statuses: completed, partial. |
p_tool_codes | text[] | No | Keep these tools. |
p_flavor_codes | text[] | No | Keep these KV flavors, by flavor_code. A run that is not a KV run has no flavor and is left out when this filter is set. |
p_search | text | No | Search words. |
p_limit | integer | No | Page size. Default 500, at most 1000. |
p_offset | integer | No | Rows to skip. Default 0. |
p_project_ids | integer[] | No | Keep these projects. |
p_date_from, p_date_to | date | No | UTC creation date range. |
p_group_by | text | No | workload (groups by tool, and a KV run by its flavor) or project. Sorts the page by group and fills the group columns. |
Returns one row per job:
| Column | Type | Description |
|---|---|---|
job_id, run_id, run_uuid, execution_group_id | mixed | The job, its newest run, and the run's execution. |
project_id, project_uuid, project_name, project_visibility_code | mixed | The project. |
workload_id, workload_code, workload_name, scenario_name | mixed | The workload and scenario. |
tool_code, tool_name, model_code, model_name, framework_code, framework_name | varchar | Tool, model, and engine. |
server_config_code, server_config_name, server_hostname, hardware_label | mixed | The machine. |
status_code, status_display | varchar | Job status. |
created_at | timestamptz | Job creation time. |
total_count | bigint | Size of the whole filtered set. Every row repeats it. |
group_key, group_label | text | The row's group: the tool code or the project id, and its name. null without p_group_by. |
group_total | bigint | Rows in the group across all pages. |
flavor_code, flavor_label | varchar | The KV flavor of a multiroundqa run, for example Distributed KV · RoCE. null for any other run. |
Errors: ORG_ACCESS_DENIED, INVALID_PAGINATION, INVALID_GROUP_BY,
INVALID_DATE_RANGE. Permission: pulse_view:read.
pulse_list_curator_facets
Returns run counts per tool, project, status, and KV flavor for a filter bar. Each facet leaves out its own filter and applies the others, so a count says how many runs that filter value would keep.
curl -fsS -X POST "$METRUM_API_URL/rpc/pulse_list_curator_facets" \
-H "Authorization: Bearer $METRUM_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d "{\"p_org_id\":\"$METRUM_ORG_ID\",\"p_search\":\"qwen\"}" | jq
| Name | Type | Required | Description |
|---|---|---|---|
p_org_id | uuid | Yes | Workspace. |
p_include_private_project_ids | integer[] | No | Private projects to include. |
p_status_codes | text[] | No | Status filter. |
p_tool_codes | text[] | No | Tool filter. |
p_flavor_codes | text[] | No | KV flavor filter. |
p_project_ids | integer[] | No | Project filter. |
p_search | text | No | Search words. |
p_date_from, p_date_to | date | No | UTC creation date range. |
| Column | Type | Description |
|---|---|---|
facet | text | tool, flavor, project, or status. The flavor facet lists KV runs only. |
facet_code | text | Tool code, flavor code, project id, or status code. |
facet_label | text | Display name. |
job_count | bigint | Matching runs. |
Errors: ORG_ACCESS_DENIED, INVALID_DATE_RANGE. Permission:
pulse_view:read. This RPC replaces pulse_list_curator_tool_facets, which
no longer exists.
pulse_list_filtered_job_ids
Returns every job id that matches the filters across all pages, newest first, at most 5000. Use it to select every run in a group.
curl -fsS -X POST "$METRUM_API_URL/rpc/pulse_list_filtered_job_ids" \
-H "Authorization: Bearer $METRUM_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d "{\"p_org_id\":\"$METRUM_ORG_ID\",\"p_project_ids\":[<project-id>]}" | jq
Parameters are the same as pulse_list_curator_facets.
| Column | Type | Description |
|---|---|---|
job_id | integer | Matching job. |
project_id | integer | Its project. |
matched_total | bigint | Matches before the 5000 cap. When it is larger than 5000, narrow the filters. |
Errors: ORG_ACCESS_DENIED, INVALID_DATE_RANGE. Permission:
pulse_view:read.
pulse_list_private_project_options
Lists the private projects of the workspace that you may include in a View.
curl -fsS -X POST "$METRUM_API_URL/rpc/pulse_list_private_project_options" \
-H "Authorization: Bearer $METRUM_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d "{\"p_org_id\":\"$METRUM_ORG_ID\"}" | jq
| Name | Type | Required | Description |
|---|---|---|---|
p_org_id | uuid | Yes | Workspace. |
| Column | Type | Description |
|---|---|---|
project_id, project_uuid, project_name | mixed | The project. |
owner_account_id, owner_display_name | mixed | Its owner. |
available_job_count | bigint | Completed or partial runs on tools shown to customers. |
last_job_at | timestamptz | Newest job time. |
Errors: ORG_ACCESS_DENIED. Permission: pulse_view:read.
View RPCs
pulse_create_view
Creates a View with the runs you name. p_source_project_ids records projects
you selected as a whole, so you can later check them for new runs.
curl -fsS -X POST "$METRUM_API_URL/rpc/pulse_create_view" \
-H "Authorization: Bearer $METRUM_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d "{
\"p_org_id\":\"$METRUM_ORG_ID\",
\"p_view_name\":\"Qwen3 on L40S\",
\"p_job_ids\":[<job-id>, <job-id>],
\"p_source_project_ids\":[<project-id>]
}" | jq
| Name | Type | Required | Description |
|---|---|---|---|
p_org_id | uuid | Yes | Workspace. Every job must belong to it. |
p_view_name | text | Yes | 1 to 100 characters. These characters are refused: / \ ? # & % < > " ' ; | ^ [ ] { }. |
p_job_ids | integer[] | Yes | At least one job. |
p_description | text | No | At most 500 characters. |
p_private_project_ids | integer[] | No | Private projects whose runs you include. |
p_view_config | text | No | A JSON object as text. Default {}. |
p_source_project_ids | integer[] | No | Projects selected as a whole. A private one must also be in p_private_project_ids. |
Returns one row with view_id (uuid) and message (View created).
Errors: VIEW_NAME_REQUIRED, VIEW_NAME_INVALID,
VIEW_DESCRIPTION_TOO_LONG, INVALID_VIEW_CONFIG, NO_JOBS_SELECTED,
JOB_NOT_FOUND, PRIVATE_PROJECT_NOT_ALLOWED, SOURCE_PROJECT_NOT_ALLOWED,
and VIEW_NAME_DUPLICATE. Permission: pulse_view:write.
pulse_add_jobs_to_view
Adds runs to a View you own and keeps the runs it already holds.
curl -fsS -X POST "$METRUM_API_URL/rpc/pulse_add_jobs_to_view" \
-H "Authorization: Bearer $METRUM_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d "{
\"p_org_id\":\"$METRUM_ORG_ID\",
\"p_view_id\":\"<view-uuid>\",
\"p_job_ids\":[<job-id>]
}" | jq
| Name | Type | Required | Description |
|---|---|---|---|
p_org_id | uuid | Yes | Workspace of the View. |
p_view_id | uuid | Yes | The View. |
p_job_ids | integer[] | Yes | At least one job. |
p_private_project_ids | integer[] | No | Private projects whose runs you add. |
p_source_project_ids | integer[] | No | Projects selected as a whole. They are added to the View's source projects. |
| Column | Type | Description |
|---|---|---|
view_id | uuid | The View. |
added_count | integer | Runs added. |
skipped_duplicate_count | integer | Runs already in the View. |
hidden_or_denied_count | integer | Runs outside the workspace, or in a private project you did not name or may not include. |
message | text | A summary of the three counts. |
Errors: VIEW_WRITE_DENIED, VIEW_NOT_FOUND, NO_JOBS_SELECTED,
PRIVATE_PROJECT_NOT_ALLOWED, SOURCE_PROJECT_NOT_ALLOWED. Permission:
pulse_view:write.
pulse_update_view
Changes the name, description, configuration, or runs of a View you own.
curl -fsS -X POST "$METRUM_API_URL/rpc/pulse_update_view" \
-H "Authorization: Bearer $METRUM_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d "{\"p_org_id\":\"$METRUM_ORG_ID\",\"p_view_id\":\"<view-uuid>\",\"p_view_name\":\"Qwen3 on L40S, October\"}" | jq
| Name | Type | Required | Description |
|---|---|---|---|
p_org_id | uuid | Yes | Workspace of the View. |
p_view_id | uuid | Yes | The View. |
p_view_name | text | No | New name, with the same rules as pulse_create_view. |
p_description | text | No | New description. An empty string clears it. |
p_job_ids | integer[] | No | The runs you want, out of the runs you can see. Runs you can see that are missing from the list leave the View. Runs you cannot see stay. |
p_private_project_ids | integer[] | No | Replaces the View's private project list. The private projects the View already includes stay allowed for p_job_ids. |
p_view_config | text | No | New configuration, a JSON object as text. |
Returns one row with view_id and message (View updated). Errors: the
pulse_create_view validation errors, plus VIEW_WRITE_DENIED. Permission:
pulse_view:write.
pulse_get_view
Returns a View's metadata as one JSON object.
curl -fsS -X POST "$METRUM_API_URL/rpc/pulse_get_view" \
-H "Authorization: Bearer $METRUM_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d "{\"p_org_id\":\"$METRUM_ORG_ID\",\"p_view_id\":\"<view-uuid>\"}" | jq
| Name | Type | Required | Description |
|---|---|---|---|
p_org_id | uuid | Yes | Workspace. |
p_view_id | uuid | Yes | The View. |
| Field | Description |
|---|---|
view_id, view_name, description, org_id, view_config, is_published | The View. |
owner_account_id, owner_display_name, created_by_account_id, updated_by_account_id, created_at, updated_at | Ownership and times. |
job_count, visible_job_count, hidden_private_job_count | All runs, runs you can see, and the difference. |
jobs | Runs you can see: job_id, project_id, run_id, added_at. |
private_projects | Included private projects: project_id, project_name, included_at. |
source_projects | Projects the View was built from as a whole, as far as you can see them: project_id, project_name, added_at. |
shares | Share recipients. Only the owner receives them. |
is_pinned, pin_order | Your pin state. |
can_read, can_edit, can_delete, can_share, can_publish, can_copy, can_download | What you can do. |
Errors: VIEW_ACCESS_DENIED, VIEW_NOT_FOUND. Permission: pulse_view:read.
pulse_list_new_source_runs
Lists runs of the View's source projects that are not in the View, newest
first, at most 5000. It adds nothing. Add the runs you want with
pulse_add_jobs_to_view. A View with no source projects returns no rows.
curl -fsS -X POST "$METRUM_API_URL/rpc/pulse_list_new_source_runs" \
-H "Authorization: Bearer $METRUM_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d "{\"p_org_id\":\"$METRUM_ORG_ID\",\"p_view_id\":\"<view-uuid>\"}" | jq
| Name | Type | Required | Description |
|---|---|---|---|
p_org_id | uuid | Yes | Workspace of the View. |
p_view_id | uuid | Yes | A View you own. |
| Column | Type | Description |
|---|---|---|
job_id, project_id, project_name | mixed | The run and its project. |
tool_code, tool_name, scenario_name, model_name, framework_name, hardware_label | mixed | What ran, and where. |
status_code, status_display, created_at | mixed | Status and time. |
matched_total | bigint | Matches before the 5000 cap. |
flavor_label | varchar | The KV flavor of a KV run. null for any other run. |
The same eligibility as the Curator applies. Private source projects count only when the View already includes them and you may still include them.
Errors: ORG_ACCESS_DENIED, VIEW_NOT_FOUND, VIEW_WRITE_DENIED.
Permission: pulse_view:read.
pulse_get_view_data
Returns every data set the charts, tables, and CSV export of a View need, as one JSON object. Every data set covers only the runs you can see.
curl -fsS -X POST "$METRUM_API_URL/rpc/pulse_get_view_data" \
-H "Authorization: Bearer $METRUM_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d "{\"p_org_id\":\"$METRUM_ORG_ID\",\"p_view_id\":\"<view-uuid>\"}" | jq
| Name | Type | Required | Description |
|---|---|---|---|
p_org_id | uuid | Yes | Workspace. |
p_view_id | uuid | Yes | The View. |
The object has these keys: view, benchmark_results,
concurrency_scaling, cost_efficiency, hardware_utilization,
metrumbench_llm_outputs, multiroundqa_outputs, metrumbench_vlm_outputs,
metrumbench_asr_outputs, metrumbench_asr_audio_format_counts,
metrumbench_imagegen_outputs, metrumbench_imagegen_endpoint_outputs,
metrumbench_imagegen_image_artifacts, metrumbench_imagegen_error_counts,
telemetry_per_gpu, kyai_job_ids, job_ids, missing_jobs, and
hidden_private_jobs. Each data set is an array. benchmark_results is
ordered newest job first. missing_jobs and hidden_private_jobs count the
runs of the View that you cannot see.
In release 4.3, the RPC reads each data set with one query over all runs, and the payload is the same as before.
Errors: VIEW_ACCESS_DENIED, NO_VISIBLE_JOBS. Permission: pulse_view:read.
pulse_list_distributed_kv_metrics
Returns one row per distributed KV job of a View that you may read, with the numbers that compare two runs. A View with no distributed KV job returns no rows. A figure that was never recorded is null, never zero, which is the case for a job recorded before that percentile was stored.
curl -fsS -X POST "$METRUM_API_URL/rpc/pulse_list_distributed_kv_metrics" \
-H "Authorization: Bearer $METRUM_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d "{\"p_org_id\":\"$METRUM_ORG_ID\",\"p_view_id\":\"<view-uuid>\"}" | jq
| Name | Type | Required | Description |
|---|---|---|---|
p_org_id | uuid | Yes | Workspace. |
p_view_id | uuid | Yes | The View. |
| Column | Type | Description |
|---|---|---|
job_id, run_id, run_name, project_id, project_name | mixed | The job, its newest run, and its project. |
flavor_code, flavor_label | varchar | The KV flavor of the job. |
scenario_name, concurrency, repeat_index | mixed | The scenario, the users it ran, and the repeat. |
is_valid, invalid_reasons | mixed | Whether the result is valid, and every reason when it is not. |
input_throughput_tps, output_throughput_tps | numeric | Input and output tokens per second. |
kv_transfer_gbps | numeric | KV bytes moved between machines, times 8, over the seconds the transfers took, in gigabits per second. |
ttft_p25_s to ttft_p99_s | numeric | The 25th, 50th, 90th, 95th, and 99th percentile of time to first token, in seconds. Columns are p25, p50, p90, p95, and p99. |
tpot_*, e2e_*, handoff_* | numeric | The same five percentiles for time per output token, end-to-end latency, and KV hand-off time. |
Jobs of a private project you cannot open are left out. Errors: VIEW_ACCESS_DENIED. Permission: pulse_view:read.
Other Pulse RPCs
These RPCs did not change in release 4.3. Each takes p_org_id first.
| RPC | Purpose | Permission |
|---|---|---|
pulse_list_views(p_org_id, p_scope, p_search) | Lists Views you can read. p_scope is accessible (default), owned, shared, or published. | pulse_view:read |
pulse_copy_view(p_org_id, p_source_view_id, p_view_name) | Copies a View you can read into a new View you own, with the runs you can see and its Team source projects. | pulse_view:write |
pulse_delete_view(p_org_id, p_view_id) | Deletes a View you own. | pulse_view:write |
pulse_pin_view, pulse_unpin_view (p_org_id, p_view_id) | Pins or unpins a View for you. | pulse_view:read |
pulse_reorder_pinned_views(p_org_id, p_view_orders) | Reorders your pinned Views. p_view_orders is a JSON array as text of {"view_id": "<uuid>", "pin_order": <integer>} objects. | pulse_view:read |
pulse_share_view(p_org_id, p_view_id, p_emails) | Shares a View you own with email addresses. | pulse_view:write |
pulse_revoke_view_share(p_org_id, p_view_id, p_email) | Revokes one share. | pulse_view:write |
pulse_publish_view, pulse_unpublish_view (p_org_id, p_view_id) | Shows or hides a View for every workspace member. | pulse_view:write |