Tasks

A task assigns a fixed set of a dataset’s images to members to annotate or review. Tasks are created in the app; this resource only reads them.

list

One page of the organization’s tasks, newest first.

Source: Tasks.list

for task in client.tasks.list(limit=25):
    print(task.title, task.status, f"{task.image_count} images", f"{task.assignee_count} assignees")

pictograph tasks list --limit 25

curl -s "https://api.pictograph.io/api/v1/developer/tasks?limit=25&offset=0" \
  -H "X-API-Key: $PICTOGRAPH_API_KEY"

Returns list[Task]

class Task(BaseModel):
    """One annotation task in the organization (list item)."""
    id: str
    # The dataset the task's images belong to.
    dataset_id: str
    # Dataset name (may be null if renamed/removed).
    dataset: str | None = None
    title: str
    # 'annotate' or 'review'.
    kind: str
    # 'open' or 'done'.
    status: str
    created_at: datetime
    # Number of images frozen into the task.
    image_count: int
    # Number of org members the task is assigned to.
    assignee_count: int

iter

Every task, fetched page by page.

Source: Tasks.iter

for task in client.tasks.iter(page_size=100):
    print(task.id, task.title)

# The CLI auto-pages with --all.
pictograph tasks list --all --max-total 500

# Page manually with limit + offset until pagination.has_more is false.
curl -s "https://api.pictograph.io/api/v1/developer/tasks?limit=100&offset=100" \
  -H "X-API-Key: $PICTOGRAPH_API_KEY"

Returns OffsetPager[Task]

class Task(BaseModel):
    """One annotation task in the organization (list item)."""
    id: str
    # The dataset the task's images belong to.
    dataset_id: str
    # Dataset name (may be null if renamed/removed).
    dataset: str | None = None
    title: str
    # 'annotate' or 'review'.
    kind: str
    # 'open' or 'done'.
    status: str
    created_at: datetime
    # Number of images frozen into the task.
    image_count: int
    # Number of org members the task is assigned to.
    assignee_count: int

contributions

One task’s work per annotator: images worked, active editing time and annotations added, against the task’s totals.

Source: Tasks.contributions

breakdown = client.tasks.contributions(task="346b73d3-24d3-45bd-ae95-4da1fa4d9166")
print(breakdown.images_complete, "of", breakdown.total_images, "images complete")
for c in breakdown.contributors:
    print(c.full_name, c.images_worked, "images", f"{c.active_minutes:.1f}m", c.annotations_added, "annotations")

pictograph tasks contributions 346b73d3-24d3-45bd-ae95-4da1fa4d9166

curl -s "https://api.pictograph.io/api/v1/developer/tasks/346b73d3-24d3-45bd-ae95-4da1fa4d9166/contributions" \
  -H "X-API-Key: $PICTOGRAPH_API_KEY"

Returns TaskContributions

class TaskContributions(BaseModel):
    """Per-annotator contribution breakdown for a task, with rollup totals."""
    task_id: str
    contributors: list[TaskContribution]
    contributor_count: int
    # Total images frozen into the task.
    total_images: int
    # Task images at status 'complete' (any annotator).
    images_complete: int
    # Sum of every annotator's active editing time (seconds).
    total_active_seconds: int

    # `total_active_seconds` as minutes (float), for display.
    @property
    def total_active_minutes(self) -> float: ...

active_seconds and images_worked are exact; images_completed and annotations_added are credited to whoever last saved each image.

Common errors