---
title: "Explore"
description: "Search the public catalog - datasets and models any organization published to Explore - and start from one of them."
section: "API Reference"
order: 14
---
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`](/docs/api-reference/datasets#import_public) for a dataset,
[`models.fork`](/docs/api-reference/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`](https://github.com/pictograph-io/pictograph-sdk/blob/v1.69.160/src/pictograph/resources/explore.py)

| Arg | Type | Default | Notes |
|---|---|---|---|
| `search` | `str \| None` | `None` | Match a dataset's name or what its images show (their tags). |
| `class_name` | `str \| None` | `None` | Only datasets that have this class. |
| `sort` | `DatasetSort` | `'recent'` | `"recent"` (default), `"popular"` (most starred), `"trending"` (most starred this week) or `"alphabetical"`. |
| `limit` | `int` | `50` | Up to 100 per page; `iter_datasets` pages for you. |
| `offset` | `int` | `0` | Rows to skip. |

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

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

```bash
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]`

<details>
<summary><code>PublicDataset</code> &middot; 19 fields</summary>

```python
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
```

</details>

`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`](#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`](https://github.com/pictograph-io/pictograph-sdk/blob/v1.69.160/src/pictograph/resources/explore.py)

| Arg | Type | Default | Notes |
|---|---|---|---|
| `search` | `str \| None` | `None` | Match a dataset's name or what its images show (their tags). |
| `class_name` | `str \| None` | `None` | Only datasets that have this class. |
| `sort` | `DatasetSort` | `'recent'` | `"recent"` (default), `"popular"`, `"trending"` or `"alphabetical"`. |
| `page_size` | `int` | `50` | Rows fetched per request (up to 100). |
| `max_total` | `int \| None` | `None` | Stop after this many datasets. `None` walks them all. |

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

```bash
pictograph explore datasets --class person -n 200
```

```bash
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]`

<details>
<summary><code>PublicDataset</code> &middot; 19 fields</summary>

```python
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
```

</details>

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`](https://github.com/pictograph-io/pictograph-sdk/blob/v1.69.160/src/pictograph/resources/explore.py)

| Arg | Type | Default | Notes |
|---|---|---|---|
| `ref` | `str` | required | `"<organization>/<dataset>"` - the organization's slug and the dataset's slug or display name. Or pass the bare name and `organization=`. |
| `organization` | `str \| None` | `None` | The owning organization's slug, when `ref` is a bare name. |

```python
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)
```

```bash
pictograph explore dataset pictograph-research/coco-5k
```

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

**Returns** `PublicDataset`

<details>
<summary><code>PublicDataset</code> &middot; 19 fields</summary>

```python
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
```

</details>

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`](https://github.com/pictograph-io/pictograph-sdk/blob/v1.69.160/src/pictograph/resources/explore.py)

| Arg | Type | Default | Notes |
|---|---|---|---|
| `search` | `str \| None` | `None` | Match a model's name. |
| `model_type` | `PublicModelType \| None` | `None` | Only models of this task (`"object_detection"`, `"instance_segmentation"`, ...). |
| `sort` | `ModelSort` | `'recent'` | `"recent"` (default), `"popular"` or `"alphabetical"`. |
| `limit` | `int` | `50` | Up to 100 per page; `iter_models` pages for you. |
| `offset` | `int` | `0` | Rows to skip. |

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

```bash
pictograph explore models --task instance_segmentation --sort popular
```

```bash
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]`

<details>
<summary><code>PublicModel</code> &middot; 18 fields</summary>

```python
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
```

</details>

`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`](https://github.com/pictograph-io/pictograph-sdk/blob/v1.69.160/src/pictograph/resources/explore.py)

| Arg | Type | Default | Notes |
|---|---|---|---|
| `search` | `str \| None` | `None` | Match a model's name. |
| `model_type` | `PublicModelType \| None` | `None` | Only models of this task (`"object_detection"`, `"instance_segmentation"`, ...). |
| `sort` | `ModelSort` | `'recent'` | `"recent"` (default), `"popular"` or `"alphabetical"`. |
| `page_size` | `int` | `50` | Rows fetched per request (up to 100). |
| `max_total` | `int \| None` | `None` | Stop after this many models. `None` walks them all. |

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

```bash
pictograph explore models --search sceneparse -n 50
```

```bash
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]`

<details>
<summary><code>PublicModel</code> &middot; 18 fields</summary>

```python
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
```

</details>

## 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.

```python
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
```

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

See [`import_public`](/docs/api-reference/datasets#import_public) for the import's
options and its errors.

## Common errors

| Status | Exception | Cause |
|---|---|---|
| 404 | `NotFoundError` | No such public dataset or model (a private one reads the same) |
| 422 | `ValidationError` | An unknown `sort` or `model_type` value, or `limit` above 100 |
| - | `ValueError` | `ref` names no organization - write it as `org/dataset` |