Annotation Import Sessions

Access import sessions through client.annotation_import_sessions in the Datature Vi SDK.

client.annotations.upload() already orchestrates annotation imports end to end. It creates a session, registers files, polls status, and returns a populated AnnotationUploadResult. This resource exposes those same underlying sessions for direct read access, so you can browse historical imports, stream logs while an upload is in flight, sample the files the server received, and cancel a stuck import.

All endpoints are scoped to a single dataset.

Methods

list()

List annotation import sessions for a dataset.

sessions = client.annotation_import_sessions.list("dataset_abc123")

for session in sessions.items:
    print(session["annotationImportSessionId"], session.get("status"))

for session in client.annotation_import_sessions(dataset_id="dataset_abc123"):
    print(session["annotationImportSessionId"], session.get("status"))

failed = [
    s for s in client.annotation_import_sessions.list("dataset_abc123").all_items()
    if s.get("status") == "Failed"
]

print(f"{len(failed)} failed imports")

Returns: PaginatedResponse[dict]. A page of session documents.

get()

Fetch a single annotation import session by ID.

session = client.annotation_import_sessions.get(
    dataset_id="dataset_abc123",
    annotation_import_session_id="ais_xyz789",
)

print(session["status"])

Returns: dict. The session document, including current status and counts.

get_logs()

Fetch the structured log stream for an import session.

logs = client.annotation_import_sessions.get_logs(
    dataset_id="dataset_abc123",
    annotation_import_session_id="ais_xyz789",
)

for entry in logs.get("items", []):
    print(entry)

Returns: dict. Logs document with the platform's structured entries.

get_files_sample()

Fetch a sample of the files attached to an import session.

Useful for debugging: the platform returns a handful of the files the session received, so you can verify file naming, MIME types, and that the server interpreted them as expected.

sample = client.annotation_import_sessions.get_files_sample(
    dataset_id="dataset_abc123",
    annotation_import_session_id="ais_xyz789",
)

print(sample)

Returns: dict. Files-sample document.

update_status()

Patch the status of an annotation import session. The common use is cancelling a stuck import.

client.annotation_import_sessions.update_status(
    dataset_id="dataset_abc123",
    annotation_import_session_id="ais_xyz789",
    body={"spec": {"status": "Cancelled"}},
)

Returns: dict. The updated session document.

add_files()

Register additional files on an in-flight import session.

client.annotation_import_sessions.add_files(
    dataset_id="dataset_abc123",
    annotation_import_session_id="ais_xyz789",
    body={"files": [{"filename": "batch2.jsonl"}]},
)

Returns: dict. The files-insert response document.

Response format

Sessions are returned as plain dictionaries mirroring the platform's session documents.

Related resources