Skip to main content
GET
List factory tasks
The reference panel describes the current v3 operation. The notes below describe its v2 compatibility API. Follow the v3 request schema for current calls: v3 can move identifiers from the body or query into the URL. Keep the v2 method, path, and payload together when using the compatibility API.

v2 compatibility notes

GET /api/v2/factories/listTasks?factoryId=&taskKind=&status= returns one page of factory tasks as FactoryTask objects. Add taskKind to read one task kind (generic, software, research, ops, or creative), and status to read one of the nine task statuses (ICEBOX, BACKLOG, READY, ASSIGNED, IN_PROGRESS, BLOCKED, IN_REVIEW, COMPLETE, CANCELLED). Paging follows the same rules as List factories: limit defaults to 50, its maximum (a larger value is 400 too_big), and you follow meta.nextCursor while meta.hasMore is true. One factory. With factoryId, the page holds that factory’s tasks. With taskKind as well, tasks of other kinds are left out of the page, so a page can hold fewer rows than limit before the last page; without it, no row is left out. A malformed, missing, or unreadable factory is 404 resource_missing with the message Factory not found, including a factory that exists in an org unit you cannot read. Across factories. Without factoryId, the page holds tasks of kind taskKind (default software) from every factory you may read at the factory’s home. A task with no factory, or whose factory you may not read, is left out, so a page can hold fewer rows than limit, or none, before the last page. Rows come in index order: by status, then newest first within a status. That is not recency across statuses. Each parameter may appear once. A repeated parameter, an unknown status or taskKind, or a malformed limit or cursor is 400 bad_request. Each row says whether an agent holds the task (assignee.type agent; workerId names it when it is an active agent member of the factory’s team, as List workers returns it, and is null otherwise, because a task can record an agent that is not on the team), a person holds it (assignee.type person), or no one does (null). assigneeName is the holder’s name when Forge knows it, else null. createdBy is the creator’s recorded identity. github holds the linked pullRequest number, issue number and commitSha, each null when unset, and is null when the task has no GitHub link. Rows carry no description, project, person assignee ID, milestone, beneficiary, external tracker link, or task dependency. Use Get a factory task for the description. Tasks are written with createTask, updateTask, assignTask and transitionTask. Starting factory work is done by a person in Console.

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Query Parameters

factoryId
string

Only this factory's tasks. Omit it to list tasks of one kind across factories.

Minimum string length: 1
taskKind
enum<string>

Only tasks of this kind. Without factoryId it defaults to software.

Available options:
generic,
software,
research,
ops,
creative
status
enum<string>

Only tasks in this status.

Available options:
ICEBOX,
BACKLOG,
READY,
ASSIGNED,
IN_PROGRESS,
BLOCKED,
IN_REVIEW,
COMPLETE,
CANCELLED
limit
integer
default:50

Rows to read for this page, 1 to 50; a larger value is 400 too_big.

Required range: 1 <= x <= 50
cursor
string

The opaque meta.nextCursor from the previous page.

Minimum string length: 1

Response

Factory task page

data
object[]
required
meta
object
required

A list page's continuation. While hasMore is true, nextCursor is a string: pass it as cursor for the next page. hasMore: false ends the list; with truncated: true, more exist past what this list reads, and no cursor reaches them.