---
title: "Find the run that produced a given external reference URL"
method: GET
path: "/agent/run-by-external-reference"
tags: ["agent"]
---

# Find the run that produced a given external reference URL

`GET /agent/run-by-external-reference`

Reverse-looks up the agent run that created an EXTERNAL_REFERENCE artifact
with the given URL. The URL is matched against the canonical locator stored
when the artifact was reported via POST /harness-support/report-artifact
with artifact_type EXTERNAL_REFERENCE. Returns 404 when no matching run
exists or when the caller lacks access, to avoid leaking run existence.

## Query parameters

- `url` string, required

## Response `200`

Run found

- RunByExternalReferenceResponse — Response for a run reverse-lookup by external reference URL.
  - `run_id` string, required — The ID of the run that produced the external reference.

## Other responses

- `400` — url query parameter is missing
- `401` — Authentication required
- `404` — No run found with the given external reference URL, or caller lacks access
- `500` — Internal server error

## Changes

- **2026-08-15** `a0daf9e59774` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/warp/apis/oz-agent-api/changes/agent/run-by-external-reference/get.md)

---

[API](https://skmtc.dev/warp/apis/oz-agent-api.md) · [All operations](https://skmtc.dev/warp/apis/oz-agent-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/warp/oz-agent-api/revisions/a0daf9e59774/schema)