VLM – Samples

DatasetsInstruction DatasetsXimilar Platform

This page is part of the Custom Vision Language Models (VLM) API reference. See the overview for task modes, key concepts, the end-to-end workflow and the list of all endpoints.

Sample Endpoints

A sample is one training example. It always belongs to a dataset and inherits the dataset's mode (dataset_mode). The endpoints in this section are shared by all modes. What you attach to a sample afterwards depends on the mode:

Samples flagged as test are excluded from training and used to evaluate the trained model.

GET/v2/sample/

List Samples

List all samples, optionally filtered by dataset. Returns paginated results.

Required attributes

  • Name
    Authorization
    Type
    string
    Description

    Unique API token for authentication.

Optional attributes

  • Name
    dataset
    Type
    string
    Description

    Filter samples by dataset ID.

  • Name
    test
    Type
    boolean
    Description

    true for test samples only, false for training samples only.

  • Name
    invalid_only
    Type
    boolean
    Description

    true returns only samples that fail validation.

  • Name
    search
    Type
    string
    Description

    Search samples by name or dataset name.

  • Name
    image
    Type
    string
    Description

    Samples that use the given image ID (directly or in a step or item).

  • Name
    detection_object
    Type
    string
    Description

    Samples that use the given detection object ID.

  • Name
    page_size
    Type
    integer
    Description

    Number of results per page.

Request

GET
/v2/sample/
curl -v -XGET \
     -H 'Authorization: Token __API_TOKEN__' \
     'https://api.ximilar.com/vlm/v2/sample/?dataset=__DATASET_ID__'

Response

{
  "count": 150,
  "next": "https://api.ximilar.com/vlm/v2/sample/?dataset=8797c273-b1d3-4e6f-82bb-adfb719415fe&page=2",
  "previous": null,
  "results": [
    {
      "id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
      "dataset": "8797c273-b1d3-4e6f-82bb-adfb719415fe",
      "dataset_name": "Grading dataset",
      "dataset_mode": "instruction",
      "test": false,
      "name": "Sample 1",
      "description": null,
      "images_count": 2,
      "objects_count": 0,
      "media_count": 0,
      "valid": true,
      "variables_count": 2,
      "type": "multi_random",
      "workspace": "748e50e4-d081-4924-b9e7-f500aac6a71d"
    }
  ]
}
GET/v2/sample/{sample_id}/

Get Sample

Get details of a specific sample including its variable values (instruction mode). Steps and retrieval items are listed with their own endpoints.

Required attributes

  • Name
    Authorization
    Type
    string
    Description

    Unique API token for authentication.

  • Name
    sample_id
    Type
    string
    Description

    UUID of the sample.

Returns

  • Name
    id
    Type
    string
    Description

    UUID of the sample.

  • Name
    dataset
    Type
    string
    Description

    UUID of the dataset this sample belongs to.

  • Name
    dataset_name
    Type
    string
    Description

    Name of the parent dataset (read-only).

  • Name
    dataset_mode
    Type
    string
    Description

    Mode inherited from the dataset: instruction, agentic or retrieval (read-only).

  • Name
    test
    Type
    boolean
    Description

    Whether this is a test sample.

  • Name
    valid
    Type
    boolean
    Description

    Whether the sample passes validation for its mode (read-only, see Validate Sample).

  • Name
    name
    Type
    string
    Description

    Optional name of the sample.

  • Name
    description
    Type
    string
    Description

    Optional description of the sample.

  • Name
    type
    Type
    string
    Description

    How the sample's images are fed to the model: single, multi_random (default) or multi_ordered. See Update Sample.

  • Name
    created_date
    Type
    string
    Description

    Timestamp when the sample was created (ISO 8601 format).

  • Name
    result_template
    Type
    string
    Description

    Result template override for this sample (instruction). Falls back to the dataset's result template if not set.

  • Name
    user_prompt
    Type
    string
    Description

    User prompt override for this sample. Falls back to the dataset's user prompt if not set.

  • Name
    input_meta_data
    Type
    object
    Description

    Input metadata for this sample. Values are substituted into {{placeholders}} of the user prompt during training and inference.

  • Name
    meta_data
    Type
    object
    Description

    Additional metadata attached to the sample.

  • Name
    images_count
    Type
    integer
    Description

    Number of images attached directly to the sample (instruction mode).

  • Name
    objects_count
    Type
    integer
    Description

    Number of detection objects attached directly to the sample (instruction mode).

  • Name
    media_count
    Type
    integer
    Description

    Number of video/audio media assets attached to the sample.

  • Name
    variables_count
    Type
    integer
    Description

    Number of variable values annotated for this sample.

  • Name
    sample_variables
    Type
    array
    Description

    Annotated variable values (instruction mode), each with id, dataset_variable, variable_name, variable_type and value.

  • Name
    dataset_variables_config
    Type
    object
    Description

    Configuration of all dataset variables (type, constraints, etc.) keyed by variable name.

Request

GET
/v2/sample/{sample_id}/
curl -v -XGET \
     -H 'Authorization: Token __API_TOKEN__' \
     https://api.ximilar.com/vlm/v2/sample/__SAMPLE_ID__/

Response

{
  "id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "dataset": "8797c273-b1d3-4e6f-82bb-adfb719415fe",
  "dataset_name": "Grading dataset",
  "dataset_mode": "instruction",
  "test": false,
  "valid": true,
  "name": "Sample 1",
  "description": null,
  "type": "multi_random",
  "created_date": "2025-12-18T09:15:00.000000Z",
  "result_template": "{\"grade\": {{grade}}, \"explain\": \"{{explain}}\"}",
  "user_prompt": "Analyse the image[s]...",
  "input_meta_data": {"category": "sports card"},
  "meta_data": {},
  "images_count": 2,
  "objects_count": 0,
  "media_count": 0,
  "variables_count": 2,
  "sample_variables": [
    {
      "id": "9a1f3c2e-5b6d-4e7f-8a9b-0c1d2e3f4a5b",
      "sample": "c3d4e5f6-a7b8-9012-cdef-345678901234",
      "dataset_variable": "f82b01ed-e65d-4730-a458-2966cbf86994",
      "variable_name": "grade",
      "variable_type": "float",
      "value": 8.5
    },
    {
      "id": "1b2c3d4e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
      "sample": "c3d4e5f6-a7b8-9012-cdef-345678901234",
      "dataset_variable": "7b661f0e-7c00-4b59-b334-aca2a0249e2f",
      "variable_name": "explain",
      "variable_type": "string",
      "value": "Sharp corners, light surface wear."
    }
  ],
  "dataset_variables_config": {
    "grade": {
      "id": "f82b01ed-e65d-4730-a458-2966cbf86994",
      "type": "float",
      "required": true,
      "min_value": 0.0,
      "max_value": 10.0,
      "step_size": 0.5
    },
    "explain": {
      "id": "7b661f0e-7c00-4b59-b334-aca2a0249e2f",
      "type": "string",
      "required": false
    }
  },
  "workspace": "748e50e4-d081-4924-b9e7-f500aac6a71d"
}
POST/v2/sample/

Create Sample

Create a new, empty sample in a dataset. The sample takes the mode of the dataset. Attach images, steps or retrieval items with the mode-specific endpoints afterwards.

Required attributes

  • Name
    Authorization
    Type
    string
    Description

    Unique API token for authentication.

  • Name
    dataset
    Type
    string
    Description

    UUID of the dataset this sample belongs to.

Optional attributes

  • Name
    name
    Type
    string
    Description

    Optional name for the sample.

  • Name
    description
    Type
    string
    Description

    Optional description for the sample.

  • Name
    test
    Type
    boolean
    Description

    Whether this is a test sample (default: false).

  • Name
    type
    Type
    string
    Description

    Image usage during training: single, multi_random (default) or multi_ordered.

  • Name
    input_meta_data
    Type
    object
    Description

    Input metadata used in the user prompt. If not provided, it is auto-populated from the dataset's default_input_meta_data and the {{placeholders}} found in the user prompt.

  • Name
    user_prompt
    Type
    string
    Description

    Per-sample user prompt override.

  • Name
    result_template
    Type
    string
    Description

    Per-sample result template override (instruction mode).

  • Name
    meta_data
    Type
    object
    Description

    Additional metadata to attach to the sample.

  • Name
    workspace
    Type
    string
    Description

    UUID of the workspace (must be the dataset's workspace).

Request

POST
/v2/sample/
curl -v -XPOST \
     -H 'Authorization: Token __API_TOKEN__' \
     -H 'Content-Type: application/json' \
     -d '{
       "dataset": "__DATASET_ID__",
       "name": "Sample 1",
       "test": false
     }' \
     https://api.ximilar.com/vlm/v2/sample/

Response

{
  "id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "dataset": "8797c273-b1d3-4e6f-82bb-adfb719415fe",
  "dataset_name": "Grading dataset",
  "dataset_mode": "instruction",
  "test": false,
  "name": "Sample 1",
  "description": null,
  "type": "multi_random",
  "created_date": "2026-03-02T10:31:15.000000Z",
  "result_template": null,
  "user_prompt": null,
  "input_meta_data": {"category": "sports card"},
  "meta_data": null,
  "images_count": 0,
  "objects_count": 0,
  "media_count": 0,
  "variables_count": 0,
  "sample_variables": [],
  "dataset_variables_config": {},
  "workspace": "748e50e4-d081-4924-b9e7-f500aac6a71d"
}
PATCH/v2/sample/{sample_id}/

Update Sample

Update the editable fields of a sample. Only the provided fields are changed. A sample can be moved to another dataset of the same mode by sending a new dataset.

Required attributes

  • Name
    Authorization
    Type
    string
    Description

    Unique API token for authentication.

  • Name
    sample_id
    Type
    string
    Description

    UUID of the sample.

Optional attributes

  • Name
    name
    Type
    string
    Description

    Updated name.

  • Name
    description
    Type
    string
    Description

    Updated description.

  • Name
    test
    Type
    boolean
    Description

    Test flag (see also Set Sample as Test).

  • Name
    type
    Type
    string
    Description

    How the images are used during training:

    • single: one image of the sample is picked at random for each training step
    • multi_random: all images are used, in random order (default)
    • multi_ordered: all images are used, preserving their order
  • Name
    input_meta_data
    Type
    object
    Description

    Replaces the input metadata. Keys are substituted into {{placeholders}} of the user prompt during training and inference.

  • Name
    user_prompt
    Type
    string
    Description

    Per-sample user prompt override, or null to use the dataset's prompt.

  • Name
    result_template
    Type
    string
    Description

    Per-sample result template override (instruction mode).

  • Name
    dataset
    Type
    string
    Description

    UUID of a dataset with the same mode to move the sample to.

  • Name
    meta_data
    Type
    object
    Description

    Additional metadata.

Errors

  • Sample mode 'instruction' does not match dataset mode 'agentic'. when moving to a dataset of another mode.

Request

PATCH
/v2/sample/{sample_id}/
curl -v -XPATCH \
     -H 'Authorization: Token __API_TOKEN__' \
     -H 'Content-Type: application/json' \
     -d '{"type": "multi_ordered"}' \
     https://api.ximilar.com/vlm/v2/sample/__SAMPLE_ID__/
DELETE/v2/sample/{sample_id}/

Delete Sample

Delete a sample with its variable values, steps, retrieval items and edges. Images stay in your workspace.

Required attributes

  • Name
    Authorization
    Type
    string
    Description

    Unique API token for authentication.

  • Name
    sample_id
    Type
    string
    Description

    UUID of the sample to delete.

Request

DELETE
/v2/sample/{sample_id}/
curl -v -XDELETE \
     -H 'Authorization: Token __API_TOKEN__' \
     https://api.ximilar.com/vlm/v2/sample/__SAMPLE_ID__/
POST/v2/sample/{sample_id}/set-test/

Set Sample as Test

Mark a sample as a test sample. Test samples are used for model evaluation, not training. POST /v2/sample/{sample_id}/set-untest/ removes the flag again.

Required attributes

  • Name
    Authorization
    Type
    string
    Description

    Unique API token for authentication.

  • Name
    sample_id
    Type
    string
    Description

    UUID of the sample.

Request

POST
/v2/sample/{sample_id}/set-test/
curl -v -XPOST \
     -H 'Authorization: Token __API_TOKEN__' \
     https://api.ximilar.com/vlm/v2/sample/__SAMPLE_ID__/set-test/
POST/v2/sample/{sample_id}/validate/

Validate Sample

Run the mode-specific validation of one sample and get the list of problems. Invalid samples are skipped during training. POST /v2/sample/validate-batch/ with {"ids": ["__SAMPLE_ID__", "..."]} validates several samples at once (response {"results": {"<sample_id>": {...}}}).

Required attributes

  • Name
    Authorization
    Type
    string
    Description

    Unique API token for authentication.

  • Name
    sample_id
    Type
    string
    Description

    UUID of the sample.

Returns

  • Name
    valid
    Type
    boolean
    Description

    true when the sample can be used for training.

  • Name
    validation_errors
    Type
    array
    Description

    Problems found. Each entry has error_type and a human readable reason; agentic issues also carry step_id, role and type of the offending step.

  • Name
    validation_errors_truncated
    Type
    boolean
    Description

    true when the list was cut at 100 issues.

Request

POST
/v2/sample/{sample_id}/validate/
curl -v -XPOST \
     -H 'Authorization: Token __API_TOKEN__' \
     https://api.ximilar.com/vlm/v2/sample/__SAMPLE_ID__/validate/

Response

{
  "valid": false,
  "validation_errors_truncated": false,
  "validation_errors": [
    {
      "sample_id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
      "sample_name": "Sample 1",
      "dataset_id": "8797c273-b1d3-4e6f-82bb-adfb719415fe",
      "dataset_name": "Grading dataset",
      "step_id": null,
      "role": null,
      "type": null,
      "error_type": "missing_variables",
      "reason": "Missing variables: ['grade']. Template requires these but sample_variables is empty."
    }
  ]
}
GET/v2/sample/get-next-sample/

Next and Previous Sample

Walk through the samples of a dataset in their creation order. get-next-sample returns the sample after the given one (cycling back to the first), get-previous-sample the one before it. Both return the full sample detail.

Required attributes

  • Name
    Authorization
    Type
    string
    Description

    Unique API token for authentication.

  • Name
    sample
    Type
    string
    Description

    UUID of the current sample (query parameter).

Request

GET
/v2/sample/get-next-sample/
curl -v -XGET \
     -H 'Authorization: Token __API_TOKEN__' \
     'https://api.ximilar.com/vlm/v2/sample/get-next-sample/?sample=__SAMPLE_ID__'

Was this page helpful?