Skip to main content

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. You can rename any run via alias. For custom runs only, you can also attach or detach a data collection, or share / unshare via org_id (see below).

Sharing & unsharing rules

Only custom runs (runs without a dataset) can change org_id or data_collection_id from this endpoint. Dataset runs can only update alias here. Dataset runs inherit collection, organization, and project visibility from their dataset; share, unshare, or move those resources via PUT /datasets/{dataset_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:

  • 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 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). A private API key cannot org-share this way.
  • On an org-shared custom run not linked to a collection, changes move it to another project in your organization.
  • 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"
}

Error responses

  • 401 — Authentication failed.
  • 403 — Not allowed to update this run (for example: no access, changing org_id on another user's 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).
  • 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 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).

Example response (200)

{
  "id": 991,
  "user": "analyst@acme.com",
  "author_email": "analyst@acme.com",
  "run_type": "Custom",
  "run_source": "API Call",
  "dataset": null,
  "data_collection": "Customer Support",
  "org_id": 3,
  "number_of_metrics": 2,
  "result": 83.5,
  "threshold": 70,
  "model_slug": "gpt-4o",
  "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 or dataset run — for dataset 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"}'