VORQ Docs
Reference

Jobs and results

JobHandle, and the TextResult, MediaResult, EmbeddingResult and JobError result types.

JobHandle

Returned by client.submit(…), or built from a stored id with client.job(jobId) (no network call; never creates a job).

handle.id: string
handle.taskCid: string | null
handle.status(): Promise<string>
handle.result(timeoutSeconds?: number): Promise<TextResult | MediaResult | EmbeddingResult>
handle.cancel(): Promise<void>

id

The job id, a 0x-prefixed 32-byte hex string. Store it before waiting on anything.

taskCid

The content id of the job's sealed input, from the submission's answer. null on a handle built with client.job(id).

status()

One GET /v1/jobs/{id}. Returns queued, in_progress, completed, failed or cancelled; the last three are terminal. A row whose vorq.gas_fee or vorq.fee is missing or not a USD decimal string raises VorqError; every read of the row by result() does the same.

result()

Polls until the job is terminal, then fetches the result by content id and opens it with the client's cipher.

  • Windows under 24 hours poll every window ÷ 60 seconds, held between 2 and 60 seconds. A 24h job polls every 60 seconds for the first 15 minutes of the wait, every 180 seconds until the first hour is up, and every 600 seconds after.
  • Without timeoutSeconds, the wait is the job's window, counted from the call. A handle from submit knows the window; a handle from client.job(id) reads vorq.sla_secs from the job row, and assumes 1 hour if the row names none.
  • On expiry, raises WaitTimeout with .jobId. The job continues.
  • A failed or cancelled job raises JobFailed with .errorType.
  • A completed job that names no result, or whose bytes are not a result or do not open with this client's key, raises ResultIntegrityError.
  • A job row stating a window of zero or less seconds raises ValidationError.

cancel()

Signs Cancel(bytes32 jobId, uint64 issuedAt) with the owning wallet and posts it for the coordinator to relay to the chain.

  • A client without a signer raises ValidationError before sending.
  • The chain accepts issuedAt within ±600 s of block time. When the handle has seen the coordinator's Date header on an earlier job read, the SDK checks that bound locally and raises ValidationError without sending. A cross-origin browser can read that header only if the coordinator exposes it; otherwise the local check is skipped.
  • A job a provider has already claimed is refused with StateConflictError.

Result types

result() returns a union of classes; narrow it with instanceof:

import { EmbeddingResult, MediaResult, TextResult } from "@vorq-ai/client-sdk";

const result = await handle.result();
if (result instanceof TextResult) console.log(result.text);
else if (result instanceof MediaResult) console.log(result.frames.length, "frames");
else if (result instanceof EmbeddingResult) console.log(result.embeddings.length, "vectors");

All three carry these members:

MemberTypeMeaning
ratesRatesThe order's signed rates in USD per 1M units, { rateIn: string | null; rateOut: string | null }.
coststring((promptTok − cachedTok) × rateIn + cachedTok × rateInCached + completionTok × rateOut) / 1 000 000, rounded up to the atomic unit (0.000001 USD, minimum one) exactly as the chain charges it. See Pricing and payment.
promptToknumberPrompt units the job settled on, cached ones included: the model's own count, at most units_in. For media, the declared reference units. From the job row or batch line (vorq.prompt_tok).
cachedToknumberThe part of promptTok the model served from its cache (vorq.cached_tok).
completionToknumberOutput units the job settled on, at most units_out (vorq.completion_tok).
rateInCachedstring | nullUSD per 1M cached prompt units, as settled (vorq.rate_in_cached); null when the row carries none.
feestringThe protocol fee settlement took on top of cost, in USD, from the job row or batch line (vorq.fee). Not included in cost.
gasFeestringThe job's gas fee in USD, from the job row or batch line (vorq.gas_fee). Not included in cost.
providernumber | string | nullThe registry id of the provider that settled the job.
jobIdstring | nullThe job that produced the result.
customIdstring | nullYour customId, returned from inside the sealed payload.
rawRecord<string, unknown>The opened result object.

TextResult

MemberTypeMeaning
textstringThe generated text, joined from the output items.
outputunknown[]The raw output items (or choices, for a chat-completion-shaped result).
usageRecord<string, unknown>Token usage as the model reported it, as input_tokens, output_tokens, total_tokens. cost reads the settled counts, not this.

MediaResult

MemberTypeMeaning
framesRecord<string, unknown>[]One per image, or one for a video. Each carries b64, content_type and dimensions.
bytes()Uint8Array[]The frames decoded, in order. No network call.
seednumber | nullThe seed the model used, when reported.

bytes() decodes strictly: a frame with no b64 member, or one that is not valid base64, raises ResultIntegrityError.

EmbeddingResult

MemberTypeMeaning
embeddingsRecord<string, unknown>[]The response's data array.
modelstring | nullThe model the provider reported.
promptTokensnumberInput tokens, as the response reported them.
bytes()Uint8Array[]The vectors decoded from base64, in order.

bytes() needs encoding_format: "base64". For float vectors it raises VorqError; read .embeddings directly.

JobError

A batch line that produced no result. Returned by batch results, never raised.

MemberTypeMeaning
messagestring
typestringprovider_fail, reclaim, cancelled or expired for a line that became a job; the coordinator's refusal code for one that did not; unknown if none was given.
jobIdstring | nullThe correlation key.
customIdstring | nullNormally null: your label is sealed inside the payload, and an error has no sealed result to read it from.
rawRecord<string, unknown>The error object as received.

One result shape everywhere

SourceReturns
handle.result(), client.job(id).result()TextResult / MediaResult / EmbeddingResult; raises JobFailed on failure
batchHandle.results(), batchHandle.consume()the same three, plus JobError for a failed line
sealingFetchthe same job, rendered as an OpenAI Response object

On this page