Skip to main content

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​

TopicRule
CallerEvery Pulse RPC reads your account from the token. No Pulse RPC takes p_account_id. A request without a token fails with HTTP 401.
WorkspaceEvery Pulse RPC takes p_org_id. The Curator RPCs require that you own or belong to the workspace, or are a metrum admin.
Eligible runsA 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.
ProjectsTeam 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 projectYou 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 ownerOnly 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.
SnapshotA 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.

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 codeSQLSTATEHTTP statusCause
AUTHENTICATION_REQUIRED, or Forbidden: pulse_view:... requires authentication42501401No token.
ORG_ACCESS_DENIED42501403You do not belong to the workspace.
VIEW_ACCESS_DENIED42501403You cannot read the View.
VIEW_WRITE_DENIED42501403You do not own the View.
PRIVATE_PROJECT_NOT_ALLOWED42501403A job or source project is in a private project that you did not name or may not include.
SOURCE_PROJECT_NOT_ALLOWED42501403A source project is outside the workspace, a demo project, or a private project you cannot access.
INVALID_PAGINATION, INVALID_GROUP_BY, INVALID_DATE_RANGE22023400A bad paging, grouping, or date value.
VIEW_NAME_REQUIRED, VIEW_NAME_INVALID, VIEW_DESCRIPTION_TOO_LONG, INVALID_VIEW_CONFIG, NO_JOBS_SELECTED, JOB_NOT_FOUND22023400A bad View field, or a job outside the workspace.
VIEW_NAME_DUPLICATE23505409You already have a View with this name in the workspace.
VIEW_NOT_FOUND, NO_VISIBLE_JOBSP0002500The 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
NameTypeRequiredDescription
p_org_iduuidYesWorkspace.
p_include_private_project_idsinteger[]NoPrivate projects to include. Each must be one you may include.
p_status_codestext[]NoKeep these statuses: completed, partial.
p_tool_codestext[]NoKeep these tools.
p_flavor_codestext[]NoKeep 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_searchtextNoSearch words.
p_limitintegerNoPage size. Default 500, at most 1000.
p_offsetintegerNoRows to skip. Default 0.
p_project_idsinteger[]NoKeep these projects.
p_date_from, p_date_todateNoUTC creation date range.
p_group_bytextNoworkload (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:

ColumnTypeDescription
job_id, run_id, run_uuid, execution_group_idmixedThe job, its newest run, and the run's execution.
project_id, project_uuid, project_name, project_visibility_codemixedThe project.
workload_id, workload_code, workload_name, scenario_namemixedThe workload and scenario.
tool_code, tool_name, model_code, model_name, framework_code, framework_namevarcharTool, model, and engine.
server_config_code, server_config_name, server_hostname, hardware_labelmixedThe machine.
status_code, status_displayvarcharJob status.
created_attimestamptzJob creation time.
total_countbigintSize of the whole filtered set. Every row repeats it.
group_key, group_labeltextThe row's group: the tool code or the project id, and its name. null without p_group_by.
group_totalbigintRows in the group across all pages.
flavor_code, flavor_labelvarcharThe 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
NameTypeRequiredDescription
p_org_iduuidYesWorkspace.
p_include_private_project_idsinteger[]NoPrivate projects to include.
p_status_codestext[]NoStatus filter.
p_tool_codestext[]NoTool filter.
p_flavor_codestext[]NoKV flavor filter.
p_project_idsinteger[]NoProject filter.
p_searchtextNoSearch words.
p_date_from, p_date_todateNoUTC creation date range.
ColumnTypeDescription
facettexttool, flavor, project, or status. The flavor facet lists KV runs only.
facet_codetextTool code, flavor code, project id, or status code.
facet_labeltextDisplay name.
job_countbigintMatching 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.

ColumnTypeDescription
job_idintegerMatching job.
project_idintegerIts project.
matched_totalbigintMatches 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
NameTypeRequiredDescription
p_org_iduuidYesWorkspace.
ColumnTypeDescription
project_id, project_uuid, project_namemixedThe project.
owner_account_id, owner_display_namemixedIts owner.
available_job_countbigintCompleted or partial runs on tools shown to customers.
last_job_attimestamptzNewest 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
NameTypeRequiredDescription
p_org_iduuidYesWorkspace. Every job must belong to it.
p_view_nametextYes1 to 100 characters. These characters are refused: / \ ? # & % < > " ' ; | ^ [ ] { }.
p_job_idsinteger[]YesAt least one job.
p_descriptiontextNoAt most 500 characters.
p_private_project_idsinteger[]NoPrivate projects whose runs you include.
p_view_configtextNoA JSON object as text. Default {}.
p_source_project_idsinteger[]NoProjects 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
NameTypeRequiredDescription
p_org_iduuidYesWorkspace of the View.
p_view_iduuidYesThe View.
p_job_idsinteger[]YesAt least one job.
p_private_project_idsinteger[]NoPrivate projects whose runs you add.
p_source_project_idsinteger[]NoProjects selected as a whole. They are added to the View's source projects.
ColumnTypeDescription
view_iduuidThe View.
added_countintegerRuns added.
skipped_duplicate_countintegerRuns already in the View.
hidden_or_denied_countintegerRuns outside the workspace, or in a private project you did not name or may not include.
messagetextA 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
NameTypeRequiredDescription
p_org_iduuidYesWorkspace of the View.
p_view_iduuidYesThe View.
p_view_nametextNoNew name, with the same rules as pulse_create_view.
p_descriptiontextNoNew description. An empty string clears it.
p_job_idsinteger[]NoThe 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_idsinteger[]NoReplaces the View's private project list. The private projects the View already includes stay allowed for p_job_ids.
p_view_configtextNoNew 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
NameTypeRequiredDescription
p_org_iduuidYesWorkspace.
p_view_iduuidYesThe View.
FieldDescription
view_id, view_name, description, org_id, view_config, is_publishedThe View.
owner_account_id, owner_display_name, created_by_account_id, updated_by_account_id, created_at, updated_atOwnership and times.
job_count, visible_job_count, hidden_private_job_countAll runs, runs you can see, and the difference.
jobsRuns you can see: job_id, project_id, run_id, added_at.
private_projectsIncluded private projects: project_id, project_name, included_at.
source_projectsProjects the View was built from as a whole, as far as you can see them: project_id, project_name, added_at.
sharesShare recipients. Only the owner receives them.
is_pinned, pin_orderYour pin state.
can_read, can_edit, can_delete, can_share, can_publish, can_copy, can_downloadWhat 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
NameTypeRequiredDescription
p_org_iduuidYesWorkspace of the View.
p_view_iduuidYesA View you own.
ColumnTypeDescription
job_id, project_id, project_namemixedThe run and its project.
tool_code, tool_name, scenario_name, model_name, framework_name, hardware_labelmixedWhat ran, and where.
status_code, status_display, created_atmixedStatus and time.
matched_totalbigintMatches before the 5000 cap.
flavor_labelvarcharThe 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
NameTypeRequiredDescription
p_org_iduuidYesWorkspace.
p_view_iduuidYesThe 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
NameTypeRequiredDescription
p_org_iduuidYesWorkspace.
p_view_iduuidYesThe View.
ColumnTypeDescription
job_id, run_id, run_name, project_id, project_namemixedThe job, its newest run, and its project.
flavor_code, flavor_labelvarcharThe KV flavor of the job.
scenario_name, concurrency, repeat_indexmixedThe scenario, the users it ran, and the repeat.
is_valid, invalid_reasonsmixedWhether the result is valid, and every reason when it is not.
input_throughput_tps, output_throughput_tpsnumericInput and output tokens per second.
kv_transfer_gbpsnumericKV bytes moved between machines, times 8, over the seconds the transfers took, in gigabits per second.
ttft_p25_s to ttft_p99_snumericThe 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_*numericThe 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.

RPCPurposePermission
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