Explore

Every organization can publish datasets and models to Explore. client.explore reads that catalog - exactly what the app’s Explore pages list - so you can find a dataset to start from or a model to build on, then copy it into your organization: datasets.import_public for a dataset, models.fork for a model.

A public dataset or model lives in another organization, where a bare name is not unique, so it is addressed by its qualified public name: the organization’s slug and the dataset’s (or model’s) slug or display name.

/api/v1/developer/public/datasets/{organization}/{dataset}

Every row these methods return carries that name as ref ("pictograph-research/coco-5k"), which is what import_public and fork take. Reading the catalog is free and open to every role.

datasets

One page of public datasets, filtered by name or content and sorted.

Source: Explore.datasets

rows = client.explore.datasets(
    search="coco",
    sort="popular",
    limit=20,
)
for ds in rows:
    print(ds.ref, ds.image_count, ds.license_id)

pictograph explore datasets --search coco --sort popular -n 20

curl -s "https://api.pictograph.io/api/v1/developer/public/datasets?search=coco&sort=popular&limit=20" \
  -H "X-API-Key: $PICTOGRAPH_API_KEY"

Returns list[PublicDataset]

class PublicDataset(BaseModel):
    """A dataset in the public catalog, as Explore lists it."""
    id: str
    name: str
    slug: str | None = None
    description: str | None = None
    organization: PublicOrganization | None = None
    image_count: int = 0
    annotation_count: int = 0
    annotation_types: list[str] = []
    classes: list[DatasetClass] = []
    class_count: int = 0
    top_auto_tags: list[str] = []
    license_id: str | None = None
    star_count: int = 0
    is_fork: bool = False
    hf_repo: str | None = None
    readme: str | None = None
    published_at: datetime | None = None
    created_at: datetime | None = None
    updated_at: datetime | None = None

search matches a dataset’s name and what its images show (their content tags). A list row carries the dataset’s first few classes; dataset returns all of them and its card.

iter_datasets

Every public dataset that matches, fetched page by page as you iterate.

Source: Explore.iter_datasets

for ds in client.explore.iter_datasets(
    class_name="person",
    max_total=200,
):
    print(ds.ref, ds.classes[0].name if ds.classes else "-")

pictograph explore datasets --class person -n 200

curl -s "https://api.pictograph.io/api/v1/developer/public/datasets?class=person&offset=100&limit=100" \
  -H "X-API-Key: $PICTOGRAPH_API_KEY"

Returns OffsetPager[PublicDataset]

class PublicDataset(BaseModel):
    """A dataset in the public catalog, as Explore lists it."""
    id: str
    name: str
    slug: str | None = None
    description: str | None = None
    organization: PublicOrganization | None = None
    image_count: int = 0
    annotation_count: int = 0
    annotation_types: list[str] = []
    classes: list[DatasetClass] = []
    class_count: int = 0
    top_auto_tags: list[str] = []
    license_id: str | None = None
    star_count: int = 0
    is_fork: bool = False
    hf_repo: str | None = None
    readme: str | None = None
    published_at: datetime | None = None
    created_at: datetime | None = None
    updated_at: datetime | None = None

The CLI pages through the API itself up to -n; over REST, advance offset until pagination.has_more is false.

dataset

One public dataset: its card (readme), license, every class and its counts.

Source: Explore.dataset

ds = client.explore.dataset(
    ref="pictograph-research/coco-5k",
)
print(ds.license_id, ds.image_count, [c.name for c in ds.classes][:5])
print(ds.readme)

pictograph explore dataset pictograph-research/coco-5k

curl -s "https://api.pictograph.io/api/v1/developer/public/datasets/pictograph-research/coco-5k" \
  -H "X-API-Key: $PICTOGRAPH_API_KEY"

Returns PublicDataset

class PublicDataset(BaseModel):
    """A dataset in the public catalog, as Explore lists it."""
    id: str
    name: str
    slug: str | None = None
    description: str | None = None
    organization: PublicOrganization | None = None
    image_count: int = 0
    annotation_count: int = 0
    annotation_types: list[str] = []
    classes: list[DatasetClass] = []
    class_count: int = 0
    top_auto_tags: list[str] = []
    license_id: str | None = None
    star_count: int = 0
    is_fork: bool = False
    hf_repo: str | None = None
    readme: str | None = None
    published_at: datetime | None = None
    created_at: datetime | None = None
    updated_at: datetime | None = None

A dataset that is not public reads as a 404, exactly like one that does not exist.

models

One page of public, ready models, filtered by name or task.

Source: Explore.models

for model in client.explore.models(
    model_type="instance_segmentation",
    sort="popular",
):
    print(model.ref, model.architecture, len(model.classes))

pictograph explore models --task instance_segmentation --sort popular

curl -s "https://api.pictograph.io/api/v1/developer/public/models?model_type=instance_segmentation&sort=popular" \
  -H "X-API-Key: $PICTOGRAPH_API_KEY"

Returns list[PublicModel]

class PublicModel(BaseModel):
    """A ready model in the public catalog, as Explore lists it."""
    id: str
    name: str
    slug: str | None = None
    description: str | None = None
    organization: PublicOrganization | None = None
    model_type: str
    architecture: str | None = None
    precision: str | None = None
    class_mapping: dict[str, Any] | None = None
    metrics: dict[str, Any] = {}
    training_config: dict[str, Any] | None = None
    license_id: str | None = None
    star_count: int = 0
    weights_size_bytes: int | None = None
    is_fork: bool = False
    hf_repo: str | None = None
    created_at: datetime | None = None
    updated_at: datetime | None = None

metrics holds the model’s evaluation scores. Copy one into your organization with client.models.fork(*model.ref.split("/")), or pictograph models fork <ref>.

iter_models

Every public, ready model that matches, fetched page by page as you iterate.

Source: Explore.iter_models

for model in client.explore.iter_models(
    search="sceneparse",
    max_total=50,
):
    print(model.ref, model.architecture, model.metrics)

pictograph explore models --search sceneparse -n 50

curl -s "https://api.pictograph.io/api/v1/developer/public/models?search=sceneparse&offset=0&limit=50" \
  -H "X-API-Key: $PICTOGRAPH_API_KEY"

Returns OffsetPager[PublicModel]

class PublicModel(BaseModel):
    """A ready model in the public catalog, as Explore lists it."""
    id: str
    name: str
    slug: str | None = None
    description: str | None = None
    organization: PublicOrganization | None = None
    model_type: str
    architecture: str | None = None
    precision: str | None = None
    class_mapping: dict[str, Any] | None = None
    metrics: dict[str, Any] = {}
    training_config: dict[str, Any] | None = None
    license_id: str | None = None
    star_count: int = 0
    weights_size_bytes: int | None = None
    is_fork: bool = False
    hf_repo: str | None = None
    created_at: datetime | None = None
    updated_at: datetime | None = None

Start from a public dataset

Find one, read its card and license, then import it. The copy is private to your organization, keeps the source’s classes, license and attribution, and stays yours if the source is later unpublished.

for ds in client.explore.datasets(search="food"):
    print(ds.ref, ds.image_count, ds.license_id)

job = client.datasets.import_public(
    ref="pictograph-research/foodseg103",
    name="food-start",
)
print(job.status, job.dataset_name)   # completed food-start

pictograph explore datasets --search food
pictograph datasets import-public pictograph-research/foodseg103 --name food-start

See import_public for the import’s options and its errors.

Common errors