Sign In Get Started

Exports API

API endpoints for creating and downloading dataset exports.

Exports are downloadable ZIP archives containing images and annotations from a dataset. Export creation runs asynchronously in the background.

Create Export

POST /api/v1/developer/exports/

Create a new export job. Returns immediately while processing continues in the background.

Request Body

JSON 
{
  "dataset_name": "street-scenes",
  "name": "Training Export v1",
  "include_images": true,
  "class_filter": ["car", "person"],
  "status_filter": "complete"
}

Parameters

Parameter Type Description
dataset_name string Dataset slug (required)
name string Export name (required)
include_images boolean Include image files in ZIP (default: false)
class_filter array Only include these classes (optional)
status_filter string Only include images with this status (optional)

Example

from pictograph import Client

client = Client(api_key="{{API_KEY}}")
export = client.exports.create(
    dataset_name="{{DATASET_NAME}}",
    name="{{EXPORT_NAME}}",
    wait=True
)
import requests

response = requests.post(
    "https://api.pictograph.io/api/v1/developer/exports/",
    headers={
        "X-API-Key": "{{API_KEY}}",
        "Content-Type": "application/json"
    },
    json={
        "dataset_name": "{{DATASET_NAME}}",
        "name": "{{EXPORT_NAME}}",
        "include_images": False
    }
)
export = response.json()
curl -X POST https://api.pictograph.io/api/v1/developer/exports/ \
  -H "X-API-Key: {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "dataset_name": "{{DATASET_NAME}}",
    "name": "{{EXPORT_NAME}}",
    "include_images": false
  }'
const response = await fetch(
  "https://api.pictograph.io/api/v1/developer/exports/",
  {
    method: "POST",
    headers: {
      "X-API-Key": "{{API_KEY}}",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      dataset_name: "{{DATASET_NAME}}",
      name: "{{EXPORT_NAME}}",
      include_images: false
    })
  }
);
const exportData = await response.json();
reqBody := map[string]interface{}{
    "dataset_name":   "{{DATASET_NAME}}",
    "name":           "{{EXPORT_NAME}}",
    "include_images": false,
}
jsonBody, _ := json.Marshal(reqBody)

req, _ := http.NewRequest("POST",
    "https://api.pictograph.io/api/v1/developer/exports/",
    bytes.NewBuffer(jsonBody))
req.Header.Set("X-API-Key", "{{API_KEY}}")
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)
Response Click to collapse Click to expand
JSON 
{
  "id": "export-uuid",
  "name": "Training Export v1",
  "status": "pending",
  "created_at": "2024-01-15T10:30:00Z"
}

List Exports

GET /api/v1/developer/exports/

Parameters

Parameter Type Description
dataset_name string Filter by dataset slug (optional)
status string Filter by status: pending, processing, completed, failed

Example

from pictograph import Client

client = Client(api_key="{{API_KEY}}")
exports = client.exports.list()

for exp in exports:
    print(f"{exp['name']}: {exp['status']}")
import requests

response = requests.get(
    "https://api.pictograph.io/api/v1/developer/exports/",
    headers={"X-API-Key": "{{API_KEY}}"}
)
exports = response.json()
curl https://api.pictograph.io/api/v1/developer/exports/ \
  -H "X-API-Key: {{API_KEY}}"
const response = await fetch(
  "https://api.pictograph.io/api/v1/developer/exports/",
  { headers: { "X-API-Key": "{{API_KEY}}" } }
);
const exports = await response.json();
req, _ := http.NewRequest("GET",
    "https://api.pictograph.io/api/v1/developer/exports/", nil)
req.Header.Set("X-API-Key", "{{API_KEY}}")

resp, _ := http.DefaultClient.Do(req)
Response Click to collapse Click to expand
JSON 
[
  {
    "id": "export-uuid",
    "name": "Training Export v1",
    "dataset_name": "street-scenes",
    "status": "completed",
    "image_count": 150,
    "annotation_count": 820,
    "file_size": 52428800,
    "created_at": "2024-01-15T10:30:00Z",
    "completed_at": "2024-01-15T10:35:00Z"
  }
]

Get Export Status

GET /api/v1/developer/exports/{dataset_name}/{export_name}

Get the status and details of an export by name.

Status Values

Status Description
pending Export is queued
processing Export is being created
completed Export is ready for download
failed Export failed (check error_message)

Example

from pictograph import Client

client = Client(api_key="{{API_KEY}}")
export = client.exports.get("{{DATASET_NAME}}", "{{EXPORT_NAME}}")

print(f"Status: {export['status']}")
if export['status'] == 'completed':
    print(f"Images: {export['image_count']}")
import requests
from urllib.parse import quote

response = requests.get(
    f"https://api.pictograph.io/api/v1/developer/exports/{{DATASET_NAME}}/{quote('{{EXPORT_NAME}}')}",
    headers={"X-API-Key": "{{API_KEY}}"}
)
export = response.json()
curl "https://api.pictograph.io/api/v1/developer/exports/{{DATASET_NAME}}/{{EXPORT_NAME}}" \
  -H "X-API-Key: {{API_KEY}}"
const response = await fetch(
  "https://api.pictograph.io/api/v1/developer/exports/{{DATASET_NAME}}/" + encodeURIComponent("{{EXPORT_NAME}}"),
  { headers: { "X-API-Key": "{{API_KEY}}" } }
);
const exportData = await response.json();
exportName := url.PathEscape("{{EXPORT_NAME}}")
req, _ := http.NewRequest("GET",
    "https://api.pictograph.io/api/v1/developer/exports/{{DATASET_NAME}}/"+exportName, nil)
req.Header.Set("X-API-Key", "{{API_KEY}}")

resp, _ := http.DefaultClient.Do(req)
Response Click to collapse Click to expand
JSON 
{
  "id": "export-uuid",
  "name": "Training Export v1",
  "status": "completed",
  "image_count": 150,
  "annotation_count": 820,
  "file_size": 52428800,
  "include_images": true,
  "class_filter": ["car", "person"],
  "created_at": "2024-01-15T10:30:00Z",
  "completed_at": "2024-01-15T10:35:00Z"
}

Download Export

GET /api/v1/developer/exports/{dataset_name}/{export_name}/download

Get a signed URL to download the completed export ZIP file.

Example

from pictograph import Client

client = Client(api_key="{{API_KEY}}")
path = client.exports.download("{{DATASET_NAME}}", "{{EXPORT_NAME}}")
import requests
from urllib.parse import quote

response = requests.get(
    f"https://api.pictograph.io/api/v1/developer/exports/{{DATASET_NAME}}/{quote('{{EXPORT_NAME}}')}/download",
    headers={"X-API-Key": "{{API_KEY}}"}
)
download_url = response.json()["download_url"]
curl "https://api.pictograph.io/api/v1/developer/exports/{{DATASET_NAME}}/{{EXPORT_NAME}}/download" \
  -H "X-API-Key: {{API_KEY}}"
const response = await fetch(
  "https://api.pictograph.io/api/v1/developer/exports/{{DATASET_NAME}}/" + encodeURIComponent("{{EXPORT_NAME}}") + "/download",
  { headers: { "X-API-Key": "{{API_KEY}}" } }
);
const { download_url } = await response.json();
exportName := url.PathEscape("{{EXPORT_NAME}}")
req, _ := http.NewRequest("GET",
    "https://api.pictograph.io/api/v1/developer/exports/{{DATASET_NAME}}/"+exportName+"/download", nil)
req.Header.Set("X-API-Key", "{{API_KEY}}")
resp, _ := http.DefaultClient.Do(req)
Response Click to collapse Click to expand
JSON 
{
  "download_url": "https://storage.googleapis.com/...",
  "expires_at": "2024-01-15T11:35:00Z",
  "file_size": 52428800
}

Delete Export

DELETE /api/v1/developer/exports/{dataset_name}/{export_name}

Delete an export. Requires admin or owner role.

Example

from pictograph import Client

client = Client(api_key="{{API_KEY}}")
client.exports.delete("{{DATASET_NAME}}", "{{EXPORT_NAME}}")
import requests
from urllib.parse import quote

response = requests.delete(
    f"https://api.pictograph.io/api/v1/developer/exports/{{DATASET_NAME}}/{quote('{{EXPORT_NAME}}')}",
    headers={"X-API-Key": "{{API_KEY}}"}
)
curl -X DELETE "https://api.pictograph.io/api/v1/developer/exports/{{DATASET_NAME}}/{{EXPORT_NAME}}" \
  -H "X-API-Key: {{API_KEY}}"
await fetch(
  "https://api.pictograph.io/api/v1/developer/exports/{{DATASET_NAME}}/" + encodeURIComponent("{{EXPORT_NAME}}"),
  {
    method: "DELETE",
    headers: { "X-API-Key": "{{API_KEY}}" }
  }
);
exportName := url.PathEscape("{{EXPORT_NAME}}")
req, _ := http.NewRequest("DELETE",
    "https://api.pictograph.io/api/v1/developer/exports/{{DATASET_NAME}}/"+exportName, nil)
req.Header.Set("X-API-Key", "{{API_KEY}}")

resp, _ := http.DefaultClient.Do(req)
Copied to clipboard