> ## Documentation Index > Fetch the complete documentation index at: https://docs.ergoly.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get a task > The task as `listTasks` shows it, plus its log oldest first — the newest 200 entries, with `logOmitted` counting any older ones. An entry a key wrote shows the `platform` as its actor. ## OpenAPI ````yaml /openapi.json get /api/v1/tasks/{id} openapi: 3.1.0 info: title: Ergoly platform API version: 1.0.0 description: >- Read and change one organization's own Ergoly environment. Every route is scoped to the organization the presented credential resolves to; there is no parameter that widens it. The human-readable reference is served from the same namespace at `/api/v1/docs`, behind the same credential. The namespace's front door is `GET /api/v1`, and it is deliberately absent from `paths` below. It answers without a credential — what this API is, how an organization admin mints a key, and where the reference lives — so it is the way in to this contract rather than a part of it: it has no scope, takes no parameters, and there is nothing about it for a generated client to call. Every `unauthorized` refusal carries that same URL as `error.docs`. servers: - url: https://control.ergoly.ai security: - orgApiKey: [] tags: - name: auth description: How to present a key, what it is scoped to, and what a 401 means. - name: organization description: Which organization your credential resolves to. - name: workers description: The Slack apps and bot identities in your organization. - name: eworks description: The runtime instances under a Worker — one core, one per bound Client. - name: clients description: The customers a Worker can be scoped to, and how to bind one. - name: channels description: Which Slack rooms a Worker answers in, and who it answers as. - name: tasks description: >- Tasks handed between Workers and people, scheduled jobs, their targets, and their run history. - name: jobs description: How a provisioning run is going — the other half of every 202. - name: memory description: Read and write the memory tiers an ework mounts. - name: connections description: The credentials your agents use, and the hosts they are injected on. - name: webhooks description: Inbound URLs an outside system can POST to, each of which starts a turn. - name: activity description: Your organization's audit feed. - name: usage description: Cost, turn outcomes and a per-day pulse over a window you choose. - name: errors description: The closed set of refusal codes, and what to do about each. paths: /api/v1/tasks/{id}: get: tags: - tasks summary: Get a task description: >- The task as `listTasks` shows it, plus its log oldest first — the newest 200 entries, with `logOmitted` counting any older ones. An entry a key wrote shows the `platform` as its actor. operationId: getTask parameters: - name: id in: path required: true description: >- The task id. A malformed id answers 404, exactly as another organization's well-formed id does. schema: type: string description: >- The task id. A malformed id answers 404, exactly as another organization's well-formed id does. responses: '200': description: Success. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/TaskDetail' required: - data additionalProperties: false example: data: id: 5d6e7f80-91a2-4b3c-8d4e-5f60718293a4 organizationId: 0d4c9f2e-4b8a-4a5b-9e21-6f9c2a1b7d30 workerId: 8f1c2d3e-9a4b-4c5d-8e6f-1a2b3c4d5e6f clientId: c1a2b3c4-d5e6-4f70-8912-3a4b5c6d7e8f workClientId: c1a2b3c4-d5e6-4f70-8912-3a4b5c6d7e8f tier: client title: Morning support digest prompt: >- Summarise anything still open in this channel from the last 24 hours. schedule: kind: cron runAt: null cronExpr: 0 8 * * 1-5 timezone: Europe/London status: scheduled state: scheduled closedOutcome: null dueAt: null late: false requester: kind: person workerId: null slackUserId: U0A1B2C3D4F clerkUserId: null teamId: null openRoleId: null holder: kind: worker workerId: 8f1c2d3e-9a4b-4c5d-8e6f-1a2b3c4d5e6f slackUserId: null clerkUserId: null teamId: null openRoleId: null enabled: true silent: false targetChannel: null origin: channel: C0A1B2C3D4E channelType: channel threadTs: '1772620000.000100' slackUserId: U0A1B2C3D4F lastRunAt: '2026-03-04T08:00:04.000Z' nextRunAt: '2026-03-05T08:00:00.000Z' createdBy: agent createdByEworkId: 3b7e1c44-2d59-4f0a-9c81-5e6d7a8b9c01 createdAt: '2026-02-20T09:31:12.000Z' updatedAt: '2026-03-04T08:00:09.000Z' log: - id: e3f4a5b6-c7d8-4e9f-8a0b-1c2d3e4f5a6b kind: assigned at: '2026-03-04T09:12:40.000Z' actor: kind: worker workerId: 8f1c2d3e-9a4b-4c5d-8e6f-1a2b3c4d5e6f eworkId: 3b7e1c44-2d59-4f0a-9c81-5e6d7a8b9c01 slackUserId: null clerkUserId: null body: Needs the finance figures — over to you. payload: from: kind: worker workerId: 8f1c2d3e-9a4b-4c5d-8e6f-1a2b3c4d5e6f to: kind: person slackUserId: U0A1B2C3D4F logOmitted: 0 '401': description: '`unauthorized`' content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: '`not_found`' content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: '`rate_limited`' content: application/json: schema: $ref: '#/components/schemas/Error' security: - orgApiKey: - tasks:read components: schemas: TaskDetail: type: object description: One task with its log. properties: id: type: string description: The task id. organizationId: type: string description: Always your own organization. workerId: type: string description: The Worker that runs it. clientId: type: - string - 'null' description: >- The Client the task's scope is bound to: who owns the row. Null on a core-tier task. Where its runs execute is `workClientId`. workClientId: type: - string - 'null' description: >- Null when its targets name no client, or more than one; each run is then its own target's client's work. Otherwise the Client whose work this task is: a client-tier task's own client, or the one client its targets name. Its runs execute on that client's agent. tier: type: string enum: - core - client description: >- The tier of the task's scope, beside `clientId`. A core-tier task whose targets name a client still runs on that client's agent; see `workClientId`. title: type: string description: What the job is called. prompt: type: string description: The text the agent is given when it fires. schedule: type: object description: When the job fires. properties: kind: type: string enum: - once - cron description: A one-off instant, or a repeating expression. runAt: type: - string - 'null' format: date-time description: The instant a `once` job fires. cronExpr: type: - string - 'null' description: The five-field cron expression a `cron` job fires on. timezone: type: - string - 'null' description: IANA zone the expression is read in. required: - kind - runAt - cronExpr - timezone additionalProperties: false status: type: string description: >- The task's status in a word: `scheduled`, `in progress`, or — once closed — how it ended: `resolved`, `archived`, `declined` or `cancelled`. The same fact as `state` and `closedOutcome`, read together. state: type: string enum: - scheduled - in_progress - closed description: >- `scheduled` — assigned, not started (a recurring job waiting for its next run included). `in_progress` — work has started. `closed` — done; a closed task never fires. closedOutcome: type: - string - 'null' description: >- How a closed task ended — `resolved`, `archived`, `declined` or `cancelled`. Null on an open one. `declined` is a person saying no, not a failed run. dueAt: type: - string - 'null' format: date-time description: >- When the task is expected done. Context only: nothing fires when it passes. late: type: boolean description: >- Past `dueAt` and not closed, as of this read. Computed, never stored. requester: type: - object - 'null' description: >- Who asked for it. Null when nobody did — a task opened by an API key, or by the platform. properties: kind: type: string enum: - worker - person - team - role description: >- What kind of party this is. Every id below that is not of this kind is null. workerId: type: - string - 'null' description: The Worker, when `kind` is `worker`. slackUserId: type: - string - 'null' description: >- The person's Slack user id, when `kind` is `person` and it is known. clerkUserId: type: - string - 'null' description: >- The person's user id in this app, when `kind` is `person` and it is known. teamId: type: - string - 'null' description: The team, when `kind` is `team`. openRoleId: type: - string - 'null' description: The open role, when `kind` is `role`. required: - kind - workerId - slackUserId - clerkUserId - teamId - openRoleId additionalProperties: false holder: type: object description: Who holds it now — who the work is with. properties: kind: type: string enum: - worker - person - team - role description: >- What kind of party this is. Every id below that is not of this kind is null. workerId: type: - string - 'null' description: The Worker, when `kind` is `worker`. slackUserId: type: - string - 'null' description: >- The person's Slack user id, when `kind` is `person` and it is known. clerkUserId: type: - string - 'null' description: >- The person's user id in this app, when `kind` is `person` and it is known. teamId: type: - string - 'null' description: The team, when `kind` is `team`. openRoleId: type: - string - 'null' description: The open role, when `kind` is `role`. required: - kind - workerId - slackUserId - clerkUserId - teamId - openRoleId additionalProperties: false enabled: type: boolean description: False means it is parked and fires nothing. silent: type: boolean description: True when the fire deliberately posts nothing. targetChannel: type: - string - 'null' description: >- Where the run posts, when it is not the channel it was scheduled from. origin: type: object description: Where the job came from. properties: channel: type: - string - 'null' description: The channel it was scheduled from. channelType: type: - string - 'null' description: '`channel` | `group` | `im` | `mpim`.' threadTs: type: - string - 'null' description: The thread it was scheduled in. slackUserId: type: - string - 'null' description: Who scheduled it, when a person did. required: - channel - channelType - threadTs - slackUserId additionalProperties: false lastRunAt: type: - string - 'null' format: date-time description: When it last ran, for any of its clients. Null if it never has. nextRunAt: type: - string - 'null' format: date-time description: >- When it runs next: the soonest any enabled client is due. Null when none is scheduled. createdBy: type: string enum: - operator - agent - system description: >- Who created it: a person (`operator`), a worker (`agent`), or the platform itself (`system`). createdByEworkId: type: - string - 'null' description: The ework that created it, when an agent did. createdAt: type: string format: date-time description: When the job was created. updatedAt: type: string format: date-time description: When it last changed. log: type: array items: $ref: '#/components/schemas/TaskActivity' description: The log, oldest first — at most the newest 200 entries. logOmitted: type: integer description: Older entries not in `log`. required: - id - organizationId - workerId - clientId - workClientId - tier - title - prompt - schedule - status - state - closedOutcome - dueAt - late - requester - holder - enabled - silent - targetChannel - origin - lastRunAt - nextRunAt - createdBy - createdByEworkId - createdAt - updatedAt - log - logOmitted additionalProperties: false Error: type: object description: The one error shape. Every refusal in this namespace has it. properties: error: type: object description: The refusal. properties: code: type: string enum: - unauthorized - not_found - invalid_request - conflict - quota_exceeded - rate_limited - upstream_error - gone description: The machine-stable half. Branch on this, never on `message`. message: type: string description: Prose for a human reading a terminal. docs: type: string description: >- Where to learn how to authenticate. Present on `unauthorized` and on nothing else — it is the one refusal a caller can reach with no credential at all, so it is the one that has to say where the way in is. required: - code - message additionalProperties: false required: - error additionalProperties: false TaskActivity: type: object description: One entry on a task's log. properties: id: type: string description: The entry id. kind: type: string description: >- `created`, `assigned` (handed on), `comment`, `state_changed`, `run`, `updated`, `output` (what a Worker's turn on the task produced), `slack_send` (a Slack message a Worker's turn posted) or `slack_send_refused` (a Slack message a Worker's turn tried to send that the platform or Slack refused; `payload.reason` says why). at: type: string format: date-time description: When it happened. actor: type: object description: Who wrote the entry. properties: kind: type: string enum: - worker - person - platform description: Who wrote it. An API key's own entries are `platform`. workerId: type: - string - 'null' description: The Worker, when a Worker wrote it. eworkId: type: - string - 'null' description: The runtime it wrote from, when a Worker wrote it. slackUserId: type: - string - 'null' description: >- The person's Slack user id, when a person wrote it and it is known. clerkUserId: type: - string - 'null' description: >- The person's user id in this app, when a person wrote it and it is known. required: - kind - workerId - eworkId - slackUserId - clerkUserId additionalProperties: false body: type: - string - 'null' description: A comment's text, or the one line a person reads for this entry. payload: type: - object - 'null' description: >- The entry's facts, by kind — from and to on a handoff or a state change, the run on a run. Shape varies by `kind`. additionalProperties: true required: - id - kind - at - actor - body - payload additionalProperties: false securitySchemes: orgApiKey: type: http scheme: bearer description: >- An organization-scoped API key, minted in control under Settings → API keys. Every failure to authenticate answers one identical 401: "Provide a valid organization-scoped API key or an active session." Each operation names the one scope it is filed under, `:`, where the resource is the first path segment after `/api/v1/`; a key minted today carries all 22 of them. Scopes are RECORDED — on the key and on every audit row — and are not yet enforced: no request is refused for want of one. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.