> ## 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.
# Get a vectorization job
> Poll a vectorization job for status and, once completed, the produced SVG.
Retrieve the status of a vectorization job. While it is `pending` or `processing`,
keep polling; once `completed`, the response carries a single `svg` result object
(`image/svg+xml`) with a presigned `url` valid for **24 hours**. A cache-hit job is
born `completed` with its result already attached. Only jobs your organization
created are visible; any other id returns
[`404 not_found`](/guides/errors#not_found). Requires the `images.transform` scope.
The delivered SVG is an EU AI Act Art. 50(2) scope-out — **unsigned and
unwatermarked**. Delivery is revalidated against the server-verified ToS/AUP
acceptance on read; a missing or stale acceptance returns
`403 svg_phase1_scope_out_required`.
## Example: completed job
The `svg` is a vectorization result object; its `mime_type` is always
`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
}
```
Pass a `webhook_url` on the original
[vectorization request](/api-reference/image-ops/vectorize) to receive a signed
callback instead of polling — on a cache hit the `completed` event fires
immediately. See [Webhooks](/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_...`.
````