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 and organization 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 run with that organization.
  • Setting org_id to null unshares the run.
  • 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). You must still be a member of that organization.
  • 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).
  • 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. The collection's datasets and the collection owner's runs tied to the collection or its datasets are updated to the same org_id.

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.

Parameters

  • Path: run_id — integer.
  • Body — application/json:
{
  "org_id": "integer | null",
  "data_collection_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).
  • 404 — Run not found, or data_collection_id not found / not accessible.
  • 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.
  • 500 — Server error.

Responses

  • 200 — Updated run object with the same JSON shape as Get run.

Example response (200)

{
  "id": 991,
  "user": "analyst@acme.com",
  "author_email": "analyst@acme.com",
  "run_type": "Dataset",
  "run_source": "API Call",
  "dataset": "Support QA - March",
  "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 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}'

Attach 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):

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"}'