Sign In Get Started

Datasets API

API endpoints for listing and downloading datasets.

Datasets (also called projects) are collections of images and their annotations. These endpoints allow you to list, retrieve, and download datasets programmatically.

List Datasets

GET /api/v1/developer/datasets/

Returns all datasets in your organization.

Parameters

Parameter Type Description
limit integer Maximum results (default: 100, max: 1000)
offset integer Number of results to skip

Example

from pictograph import Client

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

for dataset in datasets:
    print(f"{dataset['name']}: {dataset['image_count']} images")
import requests

response = requests.get(
    "https://api.pictograph.io/api/v1/developer/datasets/",
    headers={"X-API-Key": "{{API_KEY}}"}
)
datasets = response.json()

for dataset in datasets:
    print(f"{dataset['name']}: {dataset['image_count']} images")
curl https://api.pictograph.io/api/v1/developer/datasets/ \
  -H "X-API-Key: {{API_KEY}}"
const response = await fetch(
  "https://api.pictograph.io/api/v1/developer/datasets/",
  { headers: { "X-API-Key": "{{API_KEY}}" } }
);
const datasets = await response.json();

datasets.forEach(dataset => {
  console.log(`${dataset.name}: ${dataset.image_count} images`);
});
package main

import (
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET",
        "https://api.pictograph.io/api/v1/developer/datasets/", nil)
    req.Header.Set("X-API-Key", "{{API_KEY}}")

    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()

    var datasets []map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&datasets)
}
Response Click to collapse Click to expand
JSON 
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Street Scene Dataset",
    "slug": "street-scene-dataset",
    "description": "Urban street scenes for autonomous driving",
    "image_count": 1500,
    "annotation_count": 8420,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-20T14:22:00Z"
  }
]

Get Dataset

GET /api/v1/developer/datasets/{id}

Get a specific dataset by ID.

Parameters

Parameter Type Description
include_images boolean Include image list (default: false)

Example

from pictograph import Client

client = Client(api_key="{{API_KEY}}")
dataset = client.datasets.get("{{DATASET_ID}}", include_images=True)

print(f"Dataset: {dataset['name']}")
print(f"Classes: {[c['name'] for c in dataset['classes']]}")
import requests

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

resp, _ := http.DefaultClient.Do(req)
Response Click to collapse Click to expand
JSON 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Street Scene Dataset",
  "slug": "street-scene-dataset",
  "description": "Urban street scenes",
  "image_count": 1500,
  "annotation_count": 8420,
  "classes": [
    {"name": "car", "color": "#FF5733"},
    {"name": "person", "color": "#33FF57"}
  ],
  "images": [
    {
      "id": "img-uuid-1",
      "filename": "scene_001.jpg",
      "annotation_count": 5
    }
  ]
}

Get Dataset by Name

GET /api/v1/developer/datasets/by-name/{name}

Get a dataset by its name (slug). This is often more convenient than using UUIDs.

Example

from pictograph import Client

client = Client(api_key="{{API_KEY}}")
dataset = client.datasets.get_by_name("{{DATASET_NAME}}")
import requests

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

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

Download Dataset

GET /api/v1/developer/datasets/by-name/{name}/download

Get signed URLs for downloading all images and annotations in a dataset.

Parameters

Parameter Type Description
mode string full, images_only, or annotations_only

Example

from pictograph import Client

client = Client(api_key="{{API_KEY}}")

# Download entire dataset to local directory
client.datasets.download(
    "{{DATASET_NAME}}",
    output_dir="./data",
    mode="full",        # "full", "images_only", or "annotations_only"
    max_workers=20      # Parallel downloads
)

# Directory structure:
# ./data/{{DATASET_NAME}}/
#   images/
#     scene_001.jpg
#   annotations/
#     scene_001.json
import requests

response = requests.get(
    "https://api.pictograph.io/api/v1/developer/datasets/by-name/{{DATASET_NAME}}/download",
    headers={"X-API-Key": "{{API_KEY}}"},
    params={"mode": "full"}
)
download_info = response.json()

# Download each image using the signed URLs
for img in download_info["images"]:
    img_resp = requests.get(img["download_url"])
    with open(f"./data/{img['filename']}", "wb") as f:
        f.write(img_resp.content)
curl "https://api.pictograph.io/api/v1/developer/datasets/by-name/{{DATASET_NAME}}/download?mode=full" \
  -H "X-API-Key: {{API_KEY}}"
const response = await fetch(
  "https://api.pictograph.io/api/v1/developer/datasets/by-name/{{DATASET_NAME}}/download?mode=full",
  { headers: { "X-API-Key": "{{API_KEY}}" } }
);
const { images } = await response.json();

// Download each image using the signed URLs
for (const img of images) {
  const imgResp = await fetch(img.download_url);
  const blob = await imgResp.blob();
  // Save blob to file (Node.js or browser)
}
req, _ := http.NewRequest("GET",
    "https://api.pictograph.io/api/v1/developer/datasets/by-name/{{DATASET_NAME}}/download?mode=full", nil)
req.Header.Set("X-API-Key", "{{API_KEY}}")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result struct {
    Images []struct {
        Filename    string `json:"filename"`
        DownloadURL string `json:"download_url"`
    } `json:"images"`
}
json.NewDecoder(resp.Body).Decode(&result)
Response Click to collapse Click to expand
JSON 
{
  "dataset": {
    "id": "dataset-uuid",
    "name": "Street Scene Dataset"
  },
  "images": [
    {
      "id": "img-uuid-1",
      "filename": "scene_001.jpg",
      "download_url": "https://storage.googleapis.com/...",
      "annotation_url": "/api/v1/developer/annotations/img-uuid-1/file"
    }
  ],
  "expires_at": "2024-01-20T15:30:00Z"
}

Note: Download URLs expire after 60 minutes. Annotation URLs point to the API and require authentication.

Copied to clipboard