Batch

Bulk image operations on one dataset. Every call takes a dataset_name plus a list of image IDs (1 to 10,000) and returns a BatchResult: partial success does not raise. Reorganizing 10,000 images is one round-trip instead of 10,000 single-image calls, and the work runs server-side as single statements rather than a loop.

There is no pictograph CLI group for batch - use the SDK or REST below. SDK source: resources/batch.py. All four operations require member+ role; delete(permanent=True) requires admin+.

move

Move images to a different virtual directory. Directory structure is metadata: the stored image bytes never move. A filename that already exists in the target is auto-suffixed (photo.png → photo-1.png) and counted in renamed rather than failing the batch.

Source: Batch.move

result = client.batch.move(
    dataset_name="my-dataset",
    image_ids=["a1b2c3d4-5e6f-4708-9a1b-2c3d4e5f6a7b"],
    target_directory_path="/sorted/cars",
)
print(result.processed, result.renamed, result.failed)

curl -s -X POST "https://api.pictograph.io/api/v1/developer/batch/images/move" \
  -H "X-API-Key: $PICTOGRAPH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dataset_name": "my-dataset", "image_ids": ["a1b2c3d4-5e6f-4708-9a1b-2c3d4e5f6a7b"], "target_directory_path": "/sorted/cars"}'

Returns BatchResult

class BatchResult(BaseModel):
    """Outcome of a batch operation."""
    success: bool
    processed: int
    failed: list[BatchFailure] = []
    affected_directories: list[str] = []
    renamed: int = 0
    operation: str | None = None

copy

Copy images to a different directory. The underlying bytes are copied server-side - instant, no data transfer - and new image rows point at the copies.

Source: Batch.copy

result = client.batch.copy(
    dataset_name="my-dataset",
    image_ids=["a1b2c3d4-5e6f-4708-9a1b-2c3d4e5f6a7b"],
    target_directory_path="/cars-copy",
    duplicate_handling="rename",
    copy_annotations=True,
)
print(result.processed, result.failed)

curl -s -X POST "https://api.pictograph.io/api/v1/developer/batch/images/copy" \
  -H "X-API-Key: $PICTOGRAPH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dataset_name": "my-dataset", "image_ids": ["a1b2c3d4-5e6f-4708-9a1b-2c3d4e5f6a7b"], "target_directory_path": "/cars-copy", "duplicate_handling": "rename", "copy_annotations": true}'

Returns BatchResult

class BatchResult(BaseModel):
    """Outcome of a batch operation."""
    success: bool
    processed: int
    failed: list[BatchFailure] = []
    affected_directories: list[str] = []
    renamed: int = 0
    operation: str | None = None

delete

Soft-archive by default: images move to the Archive tab and stay in storage, restorable with update(is_archived=False). permanent=True purges the stored bytes plus cached thumbnails, is irreversible, and requires admin+ role. Check result.operation ("archived" or "deleted") to confirm which one happened.

Source: Batch.delete

result = client.batch.delete(
    dataset_name="my-dataset",
    image_ids=["a1b2c3d4-5e6f-4708-9a1b-2c3d4e5f6a7b"],
    permanent=False,
)
print(result.operation, result.processed, result.failed)

curl -s -X POST "https://api.pictograph.io/api/v1/developer/batch/images/delete" \
  -H "X-API-Key: $PICTOGRAPH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dataset_name": "my-dataset", "image_ids": ["a1b2c3d4-5e6f-4708-9a1b-2c3d4e5f6a7b"], "permanent": false}'

Returns BatchResult

class BatchResult(BaseModel):
    """Outcome of a batch operation."""
    success: bool
    processed: int
    failed: list[BatchFailure] = []
    affected_directories: list[str] = []
    renamed: int = 0
    operation: str | None = None

update

Update metadata on a batch of images. Pass exactly the fields you want to change; None is omitted from the request, and the SDK raises ValueError if every field is None. Note this is a PATCH, and the fields are nested under updates on the wire.

Source: Batch.update

result = client.batch.update(
    dataset_name="my-dataset",
    image_ids=["a1b2c3d4-5e6f-4708-9a1b-2c3d4e5f6a7b"],
    status="complete",
    is_archived=False,
)
print(result.processed, result.failed)

curl -s -X PATCH "https://api.pictograph.io/api/v1/developer/batch/images/update" \
  -H "X-API-Key: $PICTOGRAPH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dataset_name": "my-dataset", "image_ids": ["a1b2c3d4-5e6f-4708-9a1b-2c3d4e5f6a7b"], "updates": {"status": "complete", "is_archived": false}}'

Returns BatchResult

class BatchResult(BaseModel):
    """Outcome of a batch operation."""
    success: bool
    processed: int
    failed: list[BatchFailure] = []
    affected_directories: list[str] = []
    renamed: int = 0
    operation: str | None = None

BatchResult

Common errors