> ## Documentation Index > Fetch the complete documentation index at: https://docs.vainona.ai/llms.txt > Use this file to discover all available pages before exploring further. # Pause a running job ## OpenAPI ````yaml /api-reference/openapi.yaml post /jobs/{id}/pause openapi: 3.1.0 info: title: Vainona API version: '1' license: name: Proprietary identifier: LicenseRef-Proprietary description: | The `/v1` contract from main spec §6. It is locked: changes within `/v1` are additive only, and anything breaking is `/v2`. - **Base URL.** `https://api.vainona.ai/v1`. - **Evolution.** Response objects may gain fields and enums may gain values. Clients must ignore what they do not know. Request objects reject unknown fields. - **Path segments.** Namespace names (`{ns}`) and document ids (`{id}`) may contain `/`. Send it percent-encoded as `%2F`, so that `acme/prod/tenant_123` is `acme%2Fprod%2Ftenant_123`. - **Templates (v1.5).** The judgment routes also take a namespace prefix ending in `/*`, such as `acme%2Fprod%2F*`. A judgment created there is a template: every namespace under the prefix inherits it, including ones created later. The most specific matching prefix wins (§7.7). - **Thresholds are settings (v1.5).** Named thresholds belong to the judgment, not to a version. They are evaluated at read time against the raw fields, so a change applies at once to every answer, with no recompute and no new version (§6.5). - **Entity judgments (entities, E1).** A judgment can read the documents that point at the judged one, through `context.related`, and apply only to documents matching `applies_to` (§6.5.2). Its answers carry a `watermark`, and creating one that runs `on_change` returns a replay estimate of its monthly cost until you confirm (§6.9). - **Referenced documents (entities, E3a).** A relation can also read the one document the judged document points at, through `join: {theirs: "id", mine: "attributes."}`. A change to what the relation renders of that document re-judges the judged documents that point at it and are inside `freshness.fanout.scope`: a fan-out. A large fan-out is a `fanout` job that waits for confirm (§6.5.2, §6.9). - **Idempotency.** Every write operation is idempotent by construction. `Idempotency-Key` is accepted on every mutating route and, while the node still caches the original response, returns it verbatim. - **Errors.** Every error is the `Error` envelope; the HTTP status follows the code (see each response). - **Rate limits.** Every response carries `X-RateLimit-Limit` and `X-RateLimit-Remaining`; a `rate_limited` response adds `Retry-After`, except a daily allowance that is used up, which says when it renews in `details.resets_at` instead. - **Usage.** Every response that bills carries `usage`. Judging is billed in engine-neutral judgment units: one judgment answered, per started 1,000 tokens of its compiled context and its question together, at least 1 (§9). No response ever carries an engine's price. servers: - url: https://api.vainona.ai/v1 security: - apiKey: [] tags: - name: Namespaces description: Namespaces, their settings and cache warming (§6.2, §6.11). - name: Documents description: Writes, point reads and queries (§6.3 to §6.8). - name: Judgments description: >- Judgment definitions, versions, settings, activation, backfill and template detach (§6.5, §6.9, §7.7). - name: Outcomes and calibration description: | Post what actually happened to judged documents, and read how well answers match it: the calibration report, calibrated answers and threshold recommendations (§6.10). See [calibration](/concepts/calibration). - name: Jobs description: >- Backfill, shadow, periodic, deletion, reference index and fan-out jobs (§6.2, §6.9, §7.10.5). - name: Engines description: The engine registry (§6.5, §7.4.5). paths: /jobs/{id}/pause: parameters: - $ref: '#/components/parameters/JobId' post: tags: - Jobs summary: Pause a running job operationId: pauseJob parameters: - $ref: '#/components/parameters/IdempotencyKey' responses: '200': $ref: '#/components/responses/Job' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/JobStateConflict' '413': $ref: '#/components/responses/TooLarge' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/Internal' components: parameters: JobId: name: id in: path required: true schema: type: string minLength: 1 IdempotencyKey: name: Idempotency-Key in: header description: >- Returns the original response verbatim while the node still caches it. Correctness never depends on it. schema: type: string minLength: 1 responses: Job: description: The job. headers: X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' content: application/json: schema: $ref: '#/components/schemas/Job' Unauthorized: description: '`unauthorized`: the key is missing, unknown or revoked.' content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: '`forbidden`: the key''s role or namespace prefix does not allow this.' content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: '`not_found`: the namespace, document, judgment or job does not exist.' content: application/json: schema: $ref: '#/components/schemas/Error' JobStateConflict: description: >- `conflict`: the job is not in a state that allows this action, or it is a `namespace_delete` job, which runs to the end and cannot be paused or cancelled. content: application/json: schema: $ref: '#/components/schemas/Error' TooLarge: description: >- `too_large`: the request body (on any route), a document, or the estimated query scan is over its limit. `details` carries the estimate for queries. It also answers a write that would take `default/quickstart` past its size cap (10,000 documents or 100 MB), with `details.max_documents` and `details.max_bytes`. content: application/json: schema: $ref: '#/components/schemas/Error' RateLimited: description: >- `rate_limited`: slow down. `Retry-After` says for how long, except when a daily allowance is used up: then `details.resets_at` says when it renews, and there is no `Retry-After`. headers: X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/Error' Internal: description: >- `internal`: something failed on our side. Nothing partial is returned, and a request never commits part of itself. Most `internal` errors committed nothing. A write can instead fail with a message saying it may have been committed, when we could not tell whether its batch landed (§7.2.10): it then committed all of it or none of it. Retrying a write is safe either way, because writes are idempotent. The message is generic and carries a request id, also in `details.request_id`, which support uses to find the cause. content: application/json: schema: $ref: '#/components/schemas/Error' headers: RateLimitLimit: description: Requests allowed per second for this key. schema: type: integer minimum: 0 RateLimitRemaining: description: Requests left in the current window. schema: type: integer minimum: 0 RetryAfter: description: Seconds to wait before retrying. schema: type: integer minimum: 0 schemas: Job: type: object description: | A job row (§7.10.5). A `shadow` job comes from activating a differing version without `force` (§6.9). It starts in `awaiting_confirm` and runs its sample while it waits; `report` fills in when the sample is done. `confirm` activates `version` and the job ends `done`; `cancel` leaves the active version unchanged. On a template prefix, `namespace` is the prefix. A `reference_index` job (entities, E1) builds the index an entity judgment's relations need (§6.5.2); it starts `running`, and `attribute` names the attribute it indexes. A `fanout` job (entities, E3a) re-judges the judged documents one referenced change touches (§6.9): `referenced` names the change and `estimate` its cost. It waits in `awaiting_confirm` unless the judgment's `fanout.confirm_jobs` is `false`. `confirm` is `budget_exceeded` when the estimate does not fit what is left of the namespace's budget, and `cancel` leaves the in-scope answers `stale`. required: - id - type - status - namespace - spend_usd - progress - created_at - updated_at properties: id: type: string type: type: string enum: - backfill - shadow - periodic - namespace_delete - reference_index - fanout status: type: string enum: - estimating - awaiting_confirm - running - paused - done - failed - cancelled namespace: $ref: '#/components/schemas/NamespaceOrTemplate' judgment: $ref: '#/components/schemas/Name' estimate: oneOf: - $ref: '#/components/schemas/Estimate' - type: 'null' spend_usd: type: number minimum: 0 description: Judging billed by this job so far, in US dollars. progress: type: object required: - documents_done properties: documents_done: type: integer format: int64 minimum: 0 estimated_completion_at: oneOf: - $ref: '#/components/schemas/Timestamp' - type: 'null' error: type: - string - 'null' attribute: type: - string - 'null' pattern: ^attributes\.[A-Za-z0-9_-]+$ description: >- Entities, E1 (§6.5.2). `reference_index` jobs only, as `attributes.`. The attribute whose reference index the job builds. Null for other jobs. referenced: description: Entities, E3a (§6.9). `fanout` jobs only; null for other jobs. oneOf: - $ref: '#/components/schemas/ReferencedChange' - type: 'null' version: $ref: '#/components/schemas/JudgmentVersionNumber' description: Shadow jobs only. The version being activated. report: description: | Shadow jobs only. Null while the sample runs; `progress` counts the sampled documents. A composite version's job has a `CompositeShadowReport` (§6.5.1), and when it has too few labels it fails with an `error` that starts with `insufficient_labels`. oneOf: - $ref: '#/components/schemas/ShadowReport' - $ref: '#/components/schemas/CompositeShadowReport' - type: 'null' created_at: $ref: '#/components/schemas/Timestamp' updated_at: $ref: '#/components/schemas/Timestamp' Error: type: object required: - error properties: error: type: object required: - code - message properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string details: type: object description: >- Code-specific detail, such as the scan estimate on a refused query. Every `internal` error has `request_id`. NamespaceOrTemplate: type: string description: | A namespace name, or a template prefix: a namespace path ending in `/*`, such as `acme/prod/*`, which every namespace under `acme/prod/` inherits judgments from (§7.7). Up to 256 bytes. pattern: ^[A-Za-z0-9._:/-]+(/\*)?$ minLength: 1 maxLength: 256 Name: type: string description: >- A judgment, attribute or threshold name. Names are path segments in field references, so they never contain `.`. pattern: ^[A-Za-z0-9_-]+$ minLength: 1 maxLength: 128 Estimate: type: object required: - documents - tokens - judgment_units - cost_usd - duration_s properties: documents: type: integer format: int64 minimum: 0 tokens: type: integer format: int64 minimum: 0 judgment_units: type: integer format: int64 minimum: 0 description: >- Estimated judgment units (§9), from a sample of up to 1,000 documents. cost_usd: type: number minimum: 0 description: >- What the backfill is expected to cost you, the judgment units at the graduated prices of the tiers your organization will be in, counting what it has already used this month (§9). duration_s: type: integer format: int64 minimum: 0 description: >- Expected wall-clock seconds at the bulk pool's current share of the engine's rate limit. Timestamp: type: string format: date-time description: RFC 3339, UTC. ReferencedChange: type: object description: | Entities, E3a (§6.9). The change a `fanout` job fans out: a write to the referenced document that changed what the relation renders. While the job waits for confirm, a later change to the same document moves `revision` to it, and one confirm covers them all. required: - relation - document_id - revision properties: relation: $ref: '#/components/schemas/Name' document_id: $ref: '#/components/schemas/DocumentId' revision: $ref: '#/components/schemas/Revision' description: >- The referenced document's revision at the change. Every judged document the job re-judges gets an answer with a `watermark` at or above it. JudgmentVersionNumber: type: integer format: int32 minimum: 1 ShadowReport: type: object description: | What activating `version` would change, from a shadow sample of 1,000 random documents, or every document when there are fewer (§7.3.11). Shadow evaluations are in the evaluation log with `shadow: true` and never produce answers. `current` is the answers of the active version for the sampled documents, and `candidate` the shadow evaluations. required: - documents - current - candidate - threshold_flips - recompute properties: documents: type: integer format: int64 minimum: 0 description: Documents in the sample. current: $ref: '#/components/schemas/ShadowSide' candidate: $ref: '#/components/schemas/ShadowSide' threshold_flips: type: object description: | Per named threshold, the sampled documents whose threshold boolean would change. The candidate side uses the thresholds that apply once the version is active. propertyNames: $ref: '#/components/schemas/Name' additionalProperties: $ref: '#/components/schemas/ThresholdFlips' recompute: $ref: '#/components/schemas/Estimate' description: >- What a backfill of every document under the new version would cost, as a backfill estimate. CompositeShadowReport: type: object description: | The shadow report of a composite version (§6.5.1). The job judged up to 1,000 documents with outcomes for this judgment and fitted the combiner with 5-fold cross-validation, so every document is scored by a fit that never saw its label. The baseline gets the same treatment: its cut-off is fitted by the same folds on the same outcomes, never the raw 0.5, so splitting gets no credit for what a fitted threshold alone would give. `verdict` is `better` only when the composite's accuracy beats the baseline's by more than the interval of the difference. Otherwise it is `not_better`, and the threshold recommender on the baseline is the cheaper fix. `confirm` activates the version either way, with the combiner fitted on all the documents. required: - type - documents - labels - composite - baseline - difference - parts - verdict - recompute properties: type: const: composite documents: type: integer format: int64 minimum: 0 description: Labelled documents judged and scored. labels: type: object description: The documents by their outcome. required: - 'true' - 'false' properties: 'true': type: integer format: int64 minimum: 0 'false': type: integer format: int64 minimum: 0 composite: $ref: '#/components/schemas/CrossValidated' baseline: $ref: '#/components/schemas/Baseline' difference: type: object description: >- The composite's cross-validated accuracy minus the baseline's, with its 95% interval over the documents (paired). required: - accuracy - interval properties: accuracy: type: number minimum: -1 maximum: 1 interval: $ref: '#/components/schemas/DifferenceInterval' parts: type: array description: >- Each part's weight in the combiner fitted on all the documents, on standardised log-odds, so sizes compare. A negative weight means a yes points to `false`. items: $ref: '#/components/schemas/PartWeight' features: type: array description: >- Entities, E1 (§6.5.1). Each feature's weight in the same fit, on the same standardised scale as the parts'. items: $ref: '#/components/schemas/FeatureWeight' verdict: type: string enum: - better - not_better recompute: $ref: '#/components/schemas/Estimate' description: >- What a backfill of every document under the new version would cost, as a backfill estimate. Each part is billed as a judgment. ErrorCode: type: string description: | HTTP status by code: `invalid_request` 400, `unauthorized` 401, `budget_exceeded` 402, `forbidden` 403, `not_found` 404, `conflict` 409, `too_large` 413, `engine_version_unavailable` 422, `insufficient_labels` 422, `rate_limited` 429, `internal` 500, `engine_unavailable` 503. enum: - invalid_request - unauthorized - forbidden - not_found - conflict - too_large - rate_limited - budget_exceeded - engine_unavailable - engine_version_unavailable - insufficient_labels - internal DocumentId: type: string description: Up to 128 bytes. pattern: ^[A-Za-z0-9._:/-]+$ minLength: 1 maxLength: 128 Revision: type: integer format: int64 minimum: 0 ShadowSide: type: object description: One side of a shadow report, discriminated on the judgment `type`. oneOf: - $ref: '#/components/schemas/ShadowValues' - $ref: '#/components/schemas/ShadowOptions' discriminator: propertyName: type mapping: bool: $ref: '#/components/schemas/ShadowValues' score: $ref: '#/components/schemas/ShadowValues' choice: $ref: '#/components/schemas/ShadowOptions' ThresholdFlips: type: object required: - to_true - to_false properties: to_true: type: integer format: int64 minimum: 0 description: Documents false under the active version and true under the new one. to_false: type: integer format: int64 minimum: 0 description: Documents true under the active version and false under the new one. CrossValidated: type: object description: Out-of-fold scores over the report's documents. required: - accuracy - accuracy_interval - auc properties: accuracy: $ref: '#/components/schemas/Probability' description: >- Share of documents whose out-of-fold probability is on the right side of 0.5. accuracy_interval: $ref: '#/components/schemas/MetricInterval' auc: $ref: '#/components/schemas/Probability' description: ROC AUC of the out-of-fold probabilities. Baseline: type: object description: >- The fair baseline, scored like the composite. The active version (`version`), or for a first version the composite's `question` asked on its own (`version` null). required: - version - threshold - accuracy - accuracy_interval - auc allOf: - $ref: '#/components/schemas/CrossValidated' properties: version: oneOf: - $ref: '#/components/schemas/JudgmentVersionNumber' - type: 'null' threshold: description: >- The baseline's fitted cut-off on its `p`, fitted on all the documents. Null when a higher `p` does not mean `true` more often. oneOf: - $ref: '#/components/schemas/Probability' - type: 'null' DifferenceInterval: type: object required: - lower - upper properties: lower: type: number minimum: -1 maximum: 1 upper: type: number minimum: -1 maximum: 1 PartWeight: type: object required: - name - weight properties: name: $ref: '#/components/schemas/Name' weight: type: number FeatureWeight: type: object required: - name - weight properties: name: $ref: '#/components/schemas/FeatureRef' weight: type: number ShadowValues: type: object description: The mean and histogram of `p` (bool) or `score` (score). required: - type - mean - histogram properties: type: type: string enum: - bool - score mean: type: number histogram: type: array description: >- Ten equal-width bins, from 0 to 1 for `p` and from the lowest to the highest level for `score`, lowest first. minItems: 10 maxItems: 10 items: $ref: '#/components/schemas/HistogramBin' ShadowOptions: type: object description: >- The mean probability per option, so the per-option shift is `candidate.dist` minus `current.dist`. required: - type - dist properties: type: const: choice dist: $ref: '#/components/schemas/Distribution' Probability: type: number minimum: 0 maximum: 1 MetricInterval: type: object required: - lower - upper properties: lower: $ref: '#/components/schemas/Probability' upper: $ref: '#/components/schemas/Probability' FeatureRef: type: string description: | Entities, E1 (§6.5.1). An aggregate the recipe declares, as `.count` or `.()`, such as `tickets.count` or `invoices.sum(state.amount)`. pattern: >- ^[A-Za-z0-9_-]+\.(count|(sum|min|max|latest)\((state|attributes)(\.[^.()]+)+\))$ HistogramBin: type: object description: Values in `[lower, upper)`; the last bin includes `upper`. required: - lower - upper - count properties: lower: type: number upper: type: number count: type: integer format: int64 minimum: 0 Distribution: type: object description: Probability per option or level value. Sums to 1. additionalProperties: $ref: '#/components/schemas/Probability' securitySchemes: apiKey: type: http scheme: bearer description: | An organization API key. Keys carry a role (`read_write` or `read_only`) and may be restricted to a namespace prefix such as `acme/*`, or to one namespace such as `acme/prod/tenant_1`. A prefix matches on a `/` boundary: `acme/prod/tenant_1*` covers `acme/prod/tenant_1` and everything under `acme/prod/tenant_1/`, never `acme/prod/tenant_12`. ````