# Loop run identity reference

Retain the identity of an invocation before submitting hosted work. These fields let you distinguish an uncertain response from an absent run without resubmitting with a new identity.

## Hosted invocation fields

| Field | Shape and purpose |
| --- | --- |
| Loop ID | Returned lowercase UUID of the account-owned loop |
| Version | Exactly 64 lowercase hexadecimal characters identifying the reviewed immutable package |
| Inputs | JSON object defined by that artifact, not a universal task schema |
| `Idempotency-Key` | 16–128 letters, digits, underscores or hyphens; retain it for the original invocation |
| `confirmedVersion` | Required string equal to the version in the invocation path |
| `allowCloudProcessing` | Required boolean `true` for that invocation |
| Run ID | Returned UUID identifying the accepted execution |

Invocation uses `POST /hvy/v1/loops/{loopId}/versions/{version}/invoke`. Send only `confirmedVersion`, `allowCloudProcessing` and `inputs` in an `application/json` body, at most 16,384 UTF-8 bytes. Account ownership comes from the signed-in session, not a body account ID. Browser writes require the permitted same origin.

## Reads and states

The route list below separates catalogue review, artifact inspection, invocation lookup and detail read. Invocation lookup returns identity and status; follow its returned ID with the detail read to inspect output.

HTTP 202 means acceptance. Hosted states are `queued`, `running`, `completed`, `failed`, `uncertain` and `expired`. For `completed`, check the artifact-specific output before relying on it. `uncertain` is unresolved outcome, not proof of no execution. A local read timeout does not change the recorded run state.

Inputs and output have a 24-hour retention deadline from enqueue. A run can retain its recorded status while output becomes null. Null output does not prove the run never executed.

Use [explicit invocation](/docs/loop-builder/invoke-a-version-with-explicit-inputs) and [same-run readback](/docs/loop-builder/follow-one-run-to-a-terminal-state) for the action paths. Never include cookies or credentials in the recovery worksheet.

## Responses and refusal codes

A successful invocation returns HTTP 202 with `ok:true` and `run:{id,status}`. A detail read returns HTTP 200 with `ok:true` and `run:{id,loopId,version,status,createdAt,output}`. The output schema belongs to the reviewed artifact; invocation inputs are not included in the detail read.

| Response | Narrow recovery |
| --- | --- |
| `401 authentication_required` | Sign in through the owning application, then repeat the read with the same account |
| `403 application_forbidden` or `origin_forbidden` | Use the intended application's signed-in origin; do not copy credentials or forge the origin |
| `402 subscription_required` | Check run capability, subscription and frozen-account state; do not bypass access checks |
| `400 explicit_version_consent_required` | Match the confirmed version to the path and confirm processing only after review |
| `400 inputs_required`, `invalid_request` or `idempotency_key_required` | Correct the documented input shape or key while preserving the original invocation record |
| `409 idempotency_conflict` | The retained key already belongs to a different input hash covering the loop ID, version and inputs. Inspect the original invocation and look up that same key; do not evade the conflict with a new key |
| `409 version_unavailable_or_idempotency_conflict` | The version is unavailable or unapproved. Read the catalogue and look up the original key; preserve the original invocation record rather than changing keys |
| `404 run_not_found` | Confirm the original account and returned UUID or invocation key |
| `503 loop_service_unavailable` | Preserve identity and inspect acceptance after recovery; a failed response does not prove nothing was queued |

A request body over the 16,384-byte limit is refused with `413 request_too_large`; non-JSON media types receive `415 unsupported_media_type`. Resolve these preparation errors before deliberately invoking. Do not send unrecognized body fields or a caller-selected account identity.

## Hosted loop read routes

These method/path descriptions use returned identities on the signed-in origin. They are not copy-paste shell commands and start no work.

```text
GET /hvy/v1/loops
GET /hvy/v1/loops/{loopId}/versions/{version}/artifact
GET /hvy/v1/loops/invocations/{idempotencyKey}
GET /hvy/v1/loops/runs/{runId}
```

## Related reading

[MDN: HTTP 202 Accepted](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/202) explains why request acceptance is not completion. Use the owning Loop run record to establish the actual execution state.