Update run

Endpoint: PUT /runs/{run_id}

Description

Updates a run you can modify: you own it, or it is shared with your organization (org_id matches your org) and you belong to that organization. All body fields are optional; only provided fields are applied. Content you may edit is the alias. On a run someone else still owns, alias is the only content field — org_id, data_collection_id, and project_id are not implied by that edit. On a custom run you own, you may also attach or detach a data collection or share / unshare via org_id (see below). Changing project_id on a row that is already org-shared is not part of owning the run.

Sharing & unsharing rules

Only custom runs (runs without a dataset or trace) can change org_id or data_collection_id from this endpoint. Dataset runs and trace runs can only update alias here. Dataset runs inherit collection, organization, and project visibility from their dataset; trace runs inherit organization and data collection from their trace. Share, unshare, or move those resources via PUT /datasets/{dataset_id}, PUT /traces/{trace_id}, or PUT /data-collections/{data_collection_id} instead.

You may send org_id and data_collection_id in the same request. If data_collection_id is not null and the target collection is organization-scoped (the collection has a non-null org_id), any org_id in the body must equal that collection's organization; otherwise the API returns 400. For a private collection (no org_id on the collection), include org_id: null if you also send org_id in the same request (a non-null org_id does not match the collection and is rejected).

Changing org_id:

• Setting org_id to your organization's id shares the custom run. When you newly share (org_id goes from null to your organization), include project_id in the same request (required — see Introduction — Project).
• If the run is not linked to a data collection, it receives the org_id and project_id you send.
• If the run is linked to a private data collection that you own, sharing can cascade to the whole collection: the collection, its datasets, and your runs adopt the same org_id. project_id is applied to the collection and cascades to those org-shared members, not assigned to this run alone.
• If the run is linked to an org-shared data collection, its org_id must match the collection's organization — you cannot set a different org_id or unshare the run independently. Detach it (data_collection_id: null) or change the collection instead.
• Setting org_id to null unshares the run and removes its project assignment (for the run itself; not sibling resources in the collection).
• Org-only runs (user is null on the run; the organization owns the row) cannot be unshared and cannot be moved to a different organization — org_id must equal the current value, and you must belong to that organization.
• Changing org_id on a run owned by another user (even if shared with your org) is not allowed — only that user may change org_id for their run. Org-only runs may have org_id adjusted by a member of that organization (per the rules above).

Changing data_collection_id:

• On a run owned by another user, you cannot change data_collection_id. Org-only runs may be attached or detached by a member of that organization (per the rules below).

• Linking the run to an org-shared collection forces the run's org_id to match the collection's org_id (auto-share) and inherits the collection's project when one is set. You must still be a member of that organization. The run's org_id and project follow the collection` while it remains linked.

• Linking the run to a private collection sets the run's org_id to null (the run is no longer org-shared via that link). Any project assignment on the run itself is cleared; the collection is unchanged.

• Setting data_collection_id to null detaches the run; the run's org_id is unchanged by the detach unless you also send org_id in the same request (for example org_id: null to detach and unshare together).

• Org-only runs cannot be linked to a collection whose org_id differs from the run's organization (cannot move org-owned resources to another org via a collection).

• If an org-only run is linked to a private collection you own, and you belong to the run's organization, the private collection is promoted to that organization (collection, datasets, and your runs adopt the same org_id). If the run already had a project, the collection may inherit that project assignment and cascade it to members.

Changing alias:

• Strings are trimmed; an empty string is stored as null.
• Aliases are unique per account and, for shared runs, unique within the organization.

Changing project_id (custom runs only):

• On a run owned by another user, you cannot change project_id.
• On a private custom run with no data_collection_id, sending project_id alone (without org_id) auto-shares the run with your organization and assigns it to that project when your key has organization authorization (a project-scoped key, and only into that key's project). A private API key cannot org-share this way. The owner must already belong to the chosen project.
• On an org-shared custom run not linked to a collection, changing project_id to a different project returns 403 for a non-admin, including the owner. Sending the current project_id again succeeds. A dashboard organization admin may move any org-shared run in that organization, including an org-owned run. A project-scoped or private API key cannot, even when the key's owner is an organization admin.
• You cannot set project_id to null while the run remains org-shared.
• A run linked to a data collection cannot be assigned to a project directly — assign the collection instead (or detach the run first). The API returns 400 if you try.

Parameters

• Path: run_id — integer.
• Body — application/json:

{
  "org_id": "integer | null",
  "data_collection_id": "integer | null",
  "project_id": "integer | null",
  "alias": "string | null"
}

org_id, data_collection_id, and project_id must be JSON integers. A digit string ("74"), a whole-number float (1.0), or a boolean (true / false) returns 422 before lookup. JSON null and omitting a field stay valid.

Error responses

• 401 — Authentication failed.
• 403 — Not allowed to update this run (for example: no access, changing org_id or data_collection_id on another user's run, a non-admin including the owner changing project_id on an already-shared run, or org-only org_id rules not satisfied), or API key scoping violation (project_id in the body conflicts with a project-scoped key, claim/attach conflict when the target collection or resource is assigned to a different project).
• 422 — Invalid body. org_id, data_collection_id, and project_id must be JSON integers. A digit string ("74"), a whole-number float (1.0), or a boolean (true / false) is rejected before lookup ("Input should be a valid integer"). JSON null and omitting a field are still accepted.
• 404 — Run not found or not accessible to your API key (including not assigned to the key's project); or data_collection_id not found / not claimable.
• 400 — org_id does not match the target collection's organization when both are sent and the collection is org-scoped; sending any field other than alias for a dataset or trace run (Dataset runs inherit their organization and data collection from the dataset they belong to. Change those on the dataset, not on the run.; Trace runs inherit their organization and data collection from the trace they belong to. Change those on the trace, not on the run.); changing org_id on a non-custom run; org_id not your organization when sharing; unsharing or moving an org-only run; duplicate run alias for your account or organization; org share without project_id; project_id: null while org-shared; direct project_id on a run inside a collection; invalid or inaccessible project_id.
• 500 — Server error.

Responses

• 200 — Updated run object with the same JSON shape as Get run. The dataset field may be null when the nested dataset is not accessible to your API key (same as Get run). Trace runs include trace_id; trace-scored evaluations may have record_index and record set to null, and span-level evaluations may include span_id (OTLP hex) as on Get run. For a project-scoped key that just shared a custom run it owns, can_share is false once the run is org-shared (see the example). Flag meanings: Introduction — Permissions.

Example response (200)

{
  "id": 991,
  "user": "analyst@acme.com",
  "author_email": "analyst@acme.com",
  "run_type": "Custom",
  "run_source": "API Call",
  "trace_id": null,
  "dataset": null,
  "data_collection": "Customer Support",
  "org_id": 3,
  "permissions": {
    "can_edit": true,
    "can_delete": true,
    "can_share": false,
    "can_assign_project": false,
    "can_move_collection": true
  },
  "number_of_metrics": 2,
  "result": 83.5,
  "threshold": 70,
  "model_slug": "gpt-4o",
  "reasoning_level": "none",
  "alias": "support-march",
  "aggregate_results": {
    "ans_corr": 86,
    "faith": 81
  },
  "total_cost": "0.001200000000000",
  "started_at": "2026-04-01T09:12:00Z",
  "finished_at": "2026-04-01T09:13:12Z",
  "is_gte_threshold": true,
  "evaluations": []
}

curl

Share a custom run with your organization:

curl -X PUT "https://api.aegisevals.ai/api/v1/runs/991" \
  -H "Authorization: Bearer sk_00000000000000000000000000000000" \
  -H "Content-Type: application/json" \
  -d '{"org_id":3,"project_id":5}'

Attach a custom run to a data collection (run inherits the collection's org_id):

curl -X PUT "https://api.aegisevals.ai/api/v1/runs/991" \
  -H "Authorization: Bearer sk_00000000000000000000000000000000" \
  -H "Content-Type: application/json" \
  -d '{"data_collection_id":14}'

Rename (custom, dataset, or trace run — for dataset and trace runs, only alias is allowed):

curl -X PUT "https://api.aegisevals.ai/api/v1/runs/991" \
  -H "Authorization: Bearer sk_00000000000000000000000000000000" \
  -H "Content-Type: application/json" \
  -d '{"alias":"support-march-final"}'