> ## Documentation Index
> Fetch the complete documentation index at: https://docs.samsa.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Recuperare un job di vettorizzazione
> Interroga un job di vettorizzazione per lo stato e, una volta completato, l'SVG prodotto.
Recupera lo stato di un job di vettorizzazione. Finché è `pending` o `processing`,
continua a interrogare; una volta `completed`, la risposta include un singolo oggetto
risultato `svg` (`image/svg+xml`) con un presigned `url` valido per **24 ore**. Un
job in cache hit nasce `completed` con il suo risultato già allegato. Sono visibili
solo i job creati dalla tua organizzazione; qualsiasi altro id restituisce
[`404 not_found`](/it/guides/errors#not_found). Richiede lo scope `images.transform`.
L'SVG consegnato è un'esclusione di ambito ai sensi dell'art. 50(2) del EU AI Act —
**non firmato e senza filigrana**. La consegna viene rivalidata alla lettura
rispetto all'accettazione ToS/AUP verificata lato server; un'accettazione mancante
o scaduta restituisce `403 svg_phase1_scope_out_required`.
## Esempio: job completato
L'`svg` è un oggetto risultato di vettorizzazione; il suo `mime_type` è sempre
`image/svg+xml`:
```json 200 OK theme={null}
{
"id": "a8b9c0d1-2e3f-4a4b-5c6d-7e8f9a0b1c2d",
"status": "completed",
"created_at": "2026-07-18T10:12:00Z",
"credits_used": 5,
"svg": {
"id": "4d5e6f7a-8b9c-4d0e-1f2a-3b4c5d6e7f8a",
"source_image_id": "123e4567-e89b-12d3-a456-426614174000",
"mime_type": "image/svg+xml",
"url": "https://cdn.samsa.ai/user-.../vector.svg?X-Amz-Signature=..."
},
"error": null
}
```
Passa un `webhook_url` nella
[richiesta di vettorizzazione](/it/api-reference/image-ops/vectorize) originale per
ricevere una callback firmata invece di interrogare — su un cache hit l'evento
`completed` scatta immediatamente. Vedi [Webhook](/it/guides/webhooks).
## OpenAPI
````yaml api-reference/openapi.json GET /images/vectorizations/{vectorization_id}
openapi: 3.1.0
info:
title: Samsa API
description: >-
The Samsa public REST API. Authenticate with an organization API key as a
bearer token (`Authorization: Bearer samsa_sk_...`). Errors follow a single
envelope shape; every response carries an `X-Request-ID`.
version: 1.0.0
servers:
- url: https://api.samsa.ai/public/v1
security:
- BearerAuth: []
paths:
/images/vectorizations/{vectorization_id}:
get:
tags:
- Images
summary: Retrieve a vectorization job's status and result
description: >-
Returns the job status (`pending`, `processing`, `completed`, `failed`,
`cancelled`), and — once `completed` — the produced SVG as a single
`svg` object (`image/svg+xml`) with a presigned (24h) URL. A cache-hit
job is born `completed`. Delivery revalidates the EU AI Act Art. 50(2)
acceptance facts server-authoritatively through the egress guard; if
your organization's ToS/AUP acceptance is no longer current, delivery is
refused `403 svg_phase1_scope_out_required`. Only vectorization jobs
your organization submitted through the public API are visible; anything
else returns `404`. Requires the `images.transform` scope.
operationId: get_image_vectorization_images_vectorizations__vectorization_id__get
parameters:
- name: vectorization_id
in: path
required: true
schema:
type: string
format: uuid
title: Vectorization Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PublicVectorizationDetail'
'401':
description: Missing, invalid, expired, or revoked API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'403':
description: The API key lacks the required scope for this operation.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'404':
description: Generation, or a referenced model/palette, not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'422':
description: Request validation failed (prompt, engine, resolution, ...).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'429':
description: Per-key rate limit or per-org concurrency cap exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
components:
schemas:
PublicVectorizationDetail:
properties:
id:
type: string
format: uuid
title: Id
status:
$ref: '#/components/schemas/PublicImageStatus'
description: '`pending`, `processing`, `completed`, `failed`, or `cancelled`.'
examples:
- completed
created_at:
type: string
format: date-time
title: Created At
description: When the job was submitted.
credits_used:
anyOf:
- type: integer
- type: 'null'
title: Credits Used
description: >-
Net credits charged for this job, after any refunds (0 for a cache
hit).
examples:
- 5
svg:
anyOf:
- $ref: '#/components/schemas/PublicSvgFormatResult'
- type: 'null'
description: >-
The produced SVG (`image/svg+xml`, presigned URL); null until
`completed`.
error:
anyOf:
- type: string
- type: 'null'
title: Error
description: Failure detail when `status` is `failed`; otherwise null.
type: object
required:
- id
- status
- created_at
title: PublicVectorizationDetail
description: >-
`GET /images/vectorizations/{id}` body (SAM-821 / S8.9 — ADR §7.2).
The standard async-job envelope plus ONE nullable `svg` result object
(an
`image_formats` SVG derivative built by the S8.2 egress builder via its
vectorize/SVG deferred-audit path). `created_at` is the job's submit
time from
the credit ledger (the `image_generation_tasks` table has no
`created_at`
column). A cache-hit job is born `completed` with a frozen result; a
normal job
progresses pending → processing → completed/failed.
ErrorEnvelope:
properties:
error:
$ref: '#/components/schemas/ErrorDetail'
type: object
required:
- error
title: ErrorEnvelope
description: The complete public error body — an ``error`` object wrapper (ADR §5).
PublicImageStatus:
type: string
enum:
- pending
- processing
- completed
- failed
- cancelled
title: PublicImageStatus
description: >-
Public image-job status — the lower-cased internal ``TaskStatus``.
Deliberately the plain lower-cased internal value (NOT the ADR §7.2
``PENDING -> queued`` remap): the ticket's 202 uses ``status:
"pending"`` and
its fixtures say ``pending/processing/completed/failed``, and this keeps
the
public surface consistent with the already-shipped models API
(``PublicModelStatus``).
PublicSvgFormatResult:
properties:
id:
type: string
format: uuid
title: Id
description: Stable id of the produced format (not the job id).
source_image_id:
type: string
format: uuid
title: Source Image Id
description: Id of the source image this result derives from.
mime_type:
type: string
const: image/svg+xml
title: Mime Type
description: Always `image/svg+xml`.
default: image/svg+xml
url:
type: string
title: Url
description: Presigned, time-limited (24h) HTTPS URL of the produced SVG.
type: object
required:
- id
- source_image_id
- url
title: PublicSvgFormatResult
description: A vectorization (SVG) result — Art. 50(2) scope-out surface (S8.9).
ErrorDetail:
properties:
type:
type: string
title: Type
examples:
- authentication_error
code:
type: string
title: Code
examples:
- invalid_api_key
message:
type: string
title: Message
examples:
- The provided API key is invalid, expired, or revoked.
request_id:
type: string
title: Request Id
examples:
- 8f14e45fceea167a5a36dedd4bea2543
param:
anyOf:
- type: string
- type: 'null'
title: Param
description: Present on validation errors — names the offending field.
examples:
- aspect_ratio
type: object
required:
- type
- code
- message
- request_id
title: ErrorDetail
description: The ``error`` object of the public envelope (ADR §5).
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: >-
Organization API key as a bearer token: `Authorization: Bearer
samsa_sk_...`.
````