Skip to main content
POST
/
reports
curl --request POST \
  --url https://api.coval.dev/v1/reports \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "name": "Accent sweep",
  "run_ids": [
    "8EktrIgaVxn9LfxkIynagX",
    "9FltuJhbWyoAMgymJzobhY"
  ],
  "compare_by": "persona",
  "permissions": "PRIVATE"
}
'
{
  "report": {
    "id": "01JABCDEFGHJKMNPQRSTVWXYZ0",
    "name": "Plan comparison",
    "run_ids": [
      "8EktrIgaVxn9LfxkIynagX",
      "9FltuJhbWyoAMgymJzobhY"
    ],
    "compare_by": "metadata",
    "metadata_key": "customer.plan",
    "permissions": "PUBLIC"
  }
}

Authorizations

​
x-api-key
string
header
required

API key for authentication

Body

application/json
​
name
string
required

Display name for the saved report.

Required string length: 1 - 200
Example:

"Accent sweep"

​
run_ids
string[]
required

Run IDs to include in the report. All must belong to the authenticated organization.

Required array length: 1 - 2000 elements
Example:
[
  "8EktrIgaVxn9LfxkIynagX",
  "9FltuJhbWyoAMgymJzobhY"
]
​
simulation_output_ids
string[]

Optional simulation IDs pinning the report to a subset of simulations. When set, this is the report's authoritative scope. All must belong to the authenticated organization.

Maximum array length: 10000
Example:
["AGktrIgaVxn9LfxkIynagX"]
​
source_human_review_project_id
string | null

Optional human review project the simulations were sourced from; simulation_output_ids must belong to it.

Required string length: 26
Example:

"01JABCDEFGHJKMNPQRSTVWXYZ0"

​
compare_by
enum<string>
default:none

Dimension to group and compare runs by in the report view.

Available options:
none,
run,
agent,
mutation,
persona,
test_case,
metadata
Example:

"persona"

​
metadata_key
string | null

Metadata key to group by. Required when compare_by is metadata; otherwise omit it.

Required string length: 1 - 200
Example:

"customer.plan"

​
permissions
enum<string>
default:PRIVATE

PUBLIC creates a login-free shareable report; PRIVATE keeps it organization-only.

Available options:
PUBLIC,
PRIVATE
Example:

"PRIVATE"

Response

Report created successfully

​
report
object
required