Glasser
POST/v1/runs

Run an endpoint

Admits one execution: the policy is checked, a hold is reserved for the price's maximum charge, and a run is created. Input is provider-native — construct it against the inspected input_schema. A sync endpoint always answers 200 with the terminal run inside its published timeout_ms — it never returns 202, so no polling code is needed. An async endpoint answers 200 when the run is terminal within a short server budget, otherwise 202 with the in-flight run, which you can poll or stop. Status reports whether a usable provider response won settlement, never whether the provider accepted the request: a provider 404 or 500 is a COMPLETED run whose provider_response carries the received status, charged by the price's NO_RESULT or PROVIDER_ERROR clause. The Idempotency-Key header is required — a retry with the same key returns the same run and is never charged twice, while the same key with a different request body returns 409. Balance and policy refusals happen before admission and create no run.

Request

bash
curl -X POST https://api.glasser.ai/v1/runs \
  -H "Authorization: Bearer gl_..." \
  -H "Idempotency-Key: 9f4c1c2e-your-uuid" \
  -H "Content-Type: application/json" \
  -d '{"provider":"...","endpoint":"..."}'

Headers

Idempotency-KeyrequiredA caller-generated idempotency key (a UUID is recommended). One key binds to one run: a retry with the same key after a network timeout is a read, not a second execution.

Body parameters

providerstringrequired
endpointstringrequired
inputobjectoptional
endpoint_versionintegeroptional

Response

200a terminal run: COMPLETED, FAILED or STOPPED
202an in-flight run: QUEUED or RUNNING
idstringrequired
providerstringrequired
endpointstringrequired
endpoint_versionintegerrequired
statusenumrequired
QUEUEDRUNNINGCOMPLETEDFAILEDSTOPPED
failureobjectrequired
kindenumrequired
TIMED_OUTINTERNAL
messagestringrequired
inputobjectrequired
outputunknownrequired
provider_responseobjectrequired
http_statusintegerrequired
errorunknownoptional
charge_usdstringrequired

Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats.

charge_basisobjectrequired
clauseenumrequired
ruleNO_RESULTPROVIDER_ERRORTIMED_OUTINTERNAL
quantityintegerrequired
stoppablebooleanrequired
stop_requested_atstring (ISO-8601)required

ISO-8601 UTC timestamp

created_atstring (ISO-8601)required

ISO-8601 UTC timestamp

started_atstring (ISO-8601)required

ISO-8601 UTC timestamp

completed_atstring (ISO-8601)required

ISO-8601 UTC timestamp

Errors

400validation_failedThe request does not satisfy the schema. details.issues lists the fields that failed, and details.location names the part of the request that carried them: Payload, Headers, Path, or Query.
400idempotency_key_requiredPOST /v1/runs was called without the Idempotency-Key header.
401unauthorizedThe API key is missing, malformed, revoked, or unknown.
402insufficient_balanceavailable (= balance − held) does not cover the endpoint's maximum charge. details includes required_usd and available_usd.
403endpoint_not_permittedThe key's effective policy does not include this endpoint. error.control points at policy.allowed_endpoints.
404not_foundThe resource does not exist, it does not belong to the workspace that the credentials are bound to, or the policy does not permit reading it.
409idempotency_conflictThe same Idempotency-Key is already bound to a different request body. Use a new key, or repeat the original body unchanged.
409endpoint_version_mismatchThe endpoint_version in the request is no longer current. Inspect the endpoint again, then retry with the new version and its new terms.
429rate_limitedThe rate limit is exceeded. error.retry_after_ms tells you how long to wait.
500internal_errorThe server failed. The response body does not include internal details.
503service_unavailableA sync endpoint could not reach a terminal state inside this request's budget — either the server could not start the run inside timeout_ms, or the run is still in flight. Retry with the same Idempotency-Key: the first case created nothing, the second replays the existing run.

Authentication

Requires Bearer authentication. The workspace is bound to the API key, and you cannot change it with a request header.

Authorization: Bearer gl_...

Base URL: https://api.glasser.ai