> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vlm.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Artifact

> Retrieve an artifact by session ID or execution ID.

Retrieve the raw content of an artifact using either a `session_id` (for chat completions) or an `execution_id` (for agent executions), along with the `object_id` from the response. Artifacts are binary objects generated during agent interactions, such as images, videos, audio files, and documents.

<Info>
  For a comprehensive guide on working with artifacts, including usage patterns and examples, see the [Artifacts Guide](/agents/artifacts).
</Info>

## Query Parameters

| Parameter      | Type   | Required | Description                                                                     |
| -------------- | ------ | -------- | ------------------------------------------------------------------------------- |
| `object_id`    | string | Yes      | Object ID for the artifact (format: `<type>_<6-hex-chars>`, e.g., `img_a1b2c3`) |
| `session_id`   | string | No       | Session ID from chat completions (mutually exclusive with `execution_id`)       |
| `execution_id` | string | No       | Execution ID from agent executions (mutually exclusive with `session_id`)       |

<Note>
  Either `session_id` or `execution_id` must be provided, but not both. Use `session_id` for artifacts from chat completions and `execution_id` for artifacts from agent executions.
</Note>

## Object Reference Format

Object references follow the format: `<type_prefix>_<6-digit-hex-string>` (e.g., `img_a1b2c3`).

| Artifact Type  | Prefix   | Reference Type | Python Return Type        |
| -------------- | -------- | -------------- | ------------------------- |
| Image          | `img_`   | `ImageRef`     | `PIL.Image.Image`         |
| Video          | `vid_`   | `VideoRef`     | `Path` (mp4)              |
| Audio          | `aud_`   | `AudioRef`     | `Path` (mp3)              |
| Document       | `doc_`   | `DocumentRef`  | `Path` (pdf)              |
| Reconstruction | `recon_` | `ReconRef`     | `Path` (spz)              |
| URL            | `url_`   | `UrlRef`       | `Path` (any of the above) |
| Array          | `arr_`   | `ArrayRef`     | `np.ndarray`              |

The Python SDK provides convenience methods that automatically convert artifacts to the appropriate Python types.

## Response

Returns the raw binary content of the artifact with the appropriate content type based on the artifact type.

## Get Artifact by Session ID

Use `session_id` to retrieve artifacts from chat completion responses.

<RequestExample>
  ```python Python theme={"theme":{"light":"github-light","dark":"dark-plus"}}
  from PIL import Image
  from pydantic import BaseModel, Field
  from vlmrun.client import VLMRun
  from vlmrun.types import ImageRef

  client = VLMRun(api_key="<VLMRUN_API_KEY>")

  # Define a response model with an ImageRef field
  class BlurredImageResponse(BaseModel):
      image: ImageRef = Field(..., description="The blurred image")

  # Make a chat completion request that generates an image artifact
  response = client.agent.completions.create(
      model="vlmrun-orion-1:auto",
      messages=[
          {
              "role": "user",
              "content": [
                  {"type": "text", "text": "Blur all the faces in this image"},
                  {"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}}
              ]
          }
      ],
      response_format={"type": "json_schema", "schema": BlurredImageResponse.model_json_schema()},
  )

  # Parse the response to get the artifact reference
  result = BlurredImageResponse.model_validate_json(response.choices[0].message.content)

  # Retrieve the artifact using session_id and object_id
  image: Image.Image = client.artifacts.get(
      session_id=response.session_id,
      object_id=result.image.id,
  )
  ```

  ```typescript Node.js SDK theme={"theme":{"light":"github-light","dark":"dark-plus"}}
  import { VlmRun } from "vlmrun";

  const client = new VlmRun({
    baseURL: "https://api.vlm.run/v1",
    apiKey: "<VLMRUN_API_KEY>"
  });

  // Retrieve the artifact using session_id and object_id
  const artifact = await client.artifacts.get({
    sessionId: "<SESSION_ID>",
    objectId: "img_a1b2c3"
  });
  console.log(artifact);
  ```
</RequestExample>

## Get Artifact by Execution ID

Use `execution_id` to retrieve artifacts from agent execution responses.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"dark-plus"}}
  from PIL import Image
  from pydantic import BaseModel, Field
  from vlmrun.client import VLMRun
  from vlmrun.client.types import AgentExecutionConfig, AgentExecutionResponse, ImageUrl
  from vlmrun.types import ImageRef, MessageContent

  client = VLMRun(api_key="<VLMRUN_API_KEY>")

  # Define typed inputs and response model
  class ExecutionInputs(BaseModel):
      image: MessageContent = Field(..., description="The input image")

  class ImageResponse(BaseModel):
      image: ImageRef = Field(..., description="The processed image")

  # Execute an agent
  execution: AgentExecutionResponse = client.agent.execute(
      name="image/blur-image",
      inputs=ExecutionInputs(
          image=MessageContent(type="image_url", image_url=ImageUrl(url="https://example.com/photo.jpg"))
      ),
      config=AgentExecutionConfig(
          prompt="Blur the entire image",
          response_model=ImageResponse
      )
  )

  # Wait for completion
  execution = client.executions.wait(execution.id, timeout=180)

  # Parse the response and retrieve the artifact using execution_id
  result = ImageResponse.model_validate(execution.response)
  image: Image.Image = client.artifacts.get(
      execution_id=execution.id,
      object_id=result.image.id,
  )
  ```

  ```typescript Node.js SDK theme={"theme":{"light":"github-light","dark":"dark-plus"}}
  import { VlmRun } from "vlmrun";

  const client = new VlmRun({
    baseURL: "https://api.vlm.run/v1",
    apiKey: "<VLMRUN_API_KEY>"
  });

  // Retrieve the artifact using execution_id and object_id
  const artifact = await client.artifacts.get({
    executionId: "<EXECUTION_ID>",
    objectId: "img_a1b2c3"
  });
  console.log(artifact);
  ```
</CodeGroup>


## OpenAPI

````yaml GET /v1/artifacts
openapi: 3.1.0
info:
  title: VLM Run Unified Server
  description: Unified server for VLM Run Agent and API
  termsOfService: https://vlm.run/terms-of-service
  contact:
    name: VLM Run Support Team
    url: https://vlm.run/
    email: support@vlm.run
  version: 2026-05-19.0
servers: []
security: []
paths:
  /v1/artifacts:
    get:
      tags:
        - artifacts
      summary: Get Artifact
      description: |-
        Get an artifact for a chat completion session with user authentication.

        Tries the live Redis/in-memory object store first (fast path for active
        chats where ``save_session`` has not yet persisted the object), then
        falls back to the GCS manifest for completed sessions.
      operationId: get_artifact_v1_artifacts_get
      parameters:
        - name: object_id
          in: query
          required: true
          schema:
            type: string
            description: Object ID for the artifact
            title: Object Id
          description: Object ID for the artifact
        - name: session_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Session ID for the artifact
            title: Session Id
          description: Session ID for the artifact
        - name: execution_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Execution ID for the artifact
            title: Execution Id
          description: Execution ID for the artifact
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - HTTPBearer: []
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````