Tasks - Filed Engineering

A task is a background job Filed runs for a workspace: binder ingestion, tax prep, tax review, tax advisor, or chat. Mutations like createClient and addClientDocuments return a taskId; you use the tasks API to follow that work to completion. Tasks are reached through the me query as a WorkspaceUser, so authenticate with a workspaceToken (see Authentication). All requests go to:

https://router.apps.filed.com/graphql

The `Task` type

type Task {
  id: ID!
  type: TaskType!
  status: TaskStatus!
  startedAt: String!
  completedAt: String
  errorMessage: String
  attributes: [TaskAttribute!]!
  subTasks: [SubTask!]!
  result: TaskResult!
  client: ClientShortDetails
  triggeredBy: UserShortDetails
}

enum TaskType {
  BINDER
  TAX_PREP
  TAX_REVIEW
  TAX_ADVISOR
  CHAT
}

enum TaskStatus {
  RUNNING
  COMPLETED
  FAILED
}

ID!

The task’s unique identifier. This is the value returned as taskId by the mutations that start work.

type

TaskType!

What kind of work this is: BINDER, TAX_PREP, TAX_REVIEW, TAX_ADVISOR, or CHAT.

status

TaskStatus!

RUNNING, COMPLETED, or FAILED. Poll this to know when work finishes.

startedAt

String!

ISO 8601 timestamp of when the task started.

completedAt

String

ISO 8601 timestamp of when the task finished. null while RUNNING.

errorMessage

String

A human-readable error message when status is FAILED. null otherwise.

attributes

[TaskAttribute!]!

Arbitrary name/value metadata pairs describing the task.

subTasks

[SubTask!]!

The individual stages of the task, each with its own status. Use these for granular progress while a task is RUNNING.

result

TaskResult!

The typed result of the task, resolved by type. See Task result.

client

ClientShortDetails

The client this task belongs to (id, name), when applicable.

triggeredBy

UserShortDetails

The user who started the task (id, name, email).

Supporting types

type TaskAttribute {
  name: String!
  value: String!
}

type SubTask {
  id: ID!
  type: SubTaskType!
  status: TaskStatus!
  startedAt: String!
  completedAt: String
  errorMessage: String
  errorCode: DataEntryErrorCode
}

type ClientShortDetails {
  id: ID!
  name: String!
}

type UserShortDetails {
  id: ID!
  name: String!
  email: String!
  emailHash: String
}

SubTask.type

SubTaskType!

The stage, for example CONVERT_DOCUMENTS, CLASSIFY_SUBDOCS, EXTRACT_SUBDOCS, or EXPORT_AND_INDEX. The full set of stages depends on the parent task’s type.

SubTask.errorCode

DataEntryErrorCode

A machine-readable code when a data-entry stage fails, for example INVALID_CREDENTIALS, CLIENT_NOT_FOUND, or TIMEOUT. null otherwise.

List tasks

Read workspace.tasks to list tasks across the whole workspace. Filter, page, and sort with the arguments below.

query ListTasks($filters: TaskFilters, $sortBy: SortBy, $limit: Int, $offset: Int) {
  me {
    ... on WorkspaceUser {
      workspace {
        tasks(filters: $filters, sortBy: $sortBy, limit: $limit, offset: $offset) {
          id
          type
          status
          startedAt
          completedAt
          client {
            id
            name
          }
          triggeredBy {
            id
            name
          }
        }
      }
    }
  }
}

Arguments

input TaskFilters {
  type: TaskType
  status: TaskStatus
  triggeredBy: ID
  search: String
}

input SortBy {
  field: String!
  order: SortByOrder!   # ASC | DESC
}

filters.type

TaskType

Return only tasks of this type.

filters.status

TaskStatus

Return only tasks in this status (RUNNING, COMPLETED, FAILED).

filters.triggeredBy

Return only tasks started by this user.

filters.search

String

Free-text search over task metadata.

sortBy

SortBy

Sort order, for example { "field": "startedAt", "order": "DESC" }.

limit

Int

Maximum number of tasks to return.

offset

Int

Number of tasks to skip, for pagination.

curl -X POST https://router.apps.filed.com/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_WORKSPACE_TOKEN" \
  -d '{
    "query": "query ListTasks($filters: TaskFilters, $sortBy: SortBy, $limit: Int) { me { ... on WorkspaceUser { workspace { tasks(filters: $filters, sortBy: $sortBy, limit: $limit) { id type status startedAt completedAt client { id name } triggeredBy { id name } } } } } }",
    "variables": {
      "filters": { "type": "BINDER", "status": "RUNNING" },
      "sortBy": { "field": "startedAt", "order": "DESC" },
      "limit": 20
    }
  }'

{
  "data": {
    "me": {
      "workspace": {
        "tasks": [
          {
            "id": "018f9c2b-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
            "type": "BINDER",
            "status": "RUNNING",
            "startedAt": "2026-07-04T09:15:00.000Z",
            "completedAt": null,
            "client": {
              "id": "018f9c2a-3d5f-7a10-b2c4-9e8d7f6a5b4c",
              "name": "Jane Taxpayer"
            },
            "triggeredBy": {
              "id": "019f0fb6-26e9-74b7-a842-cb43a2a41682",
              "name": "Jane Preparer"
            }
          }
        ]
      }
    }
  }
}

Check a single task’s status

There is no task(id:) query. To follow one task (for example the taskId returned by createClient or addClientDocuments), list the tasks for its client with client.tasks and read the entry whose id matches. Because a client’s task list is small and typed, this is the reliable way to poll a specific task.

query ClientTaskStatus($clientId: ID!, $type: TaskType) {
  me {
    ... on WorkspaceUser {
      workspace {
        clients(filters: { ids: [$clientId] }) {
          tasks(type: $type) {
            id
            status
            startedAt
            completedAt
            errorMessage
            subTasks {
              type
              status
            }
          }
        }
      }
    }
  }
}

Client.tasks accepts these arguments:

tasks(type: TaskType, status: TaskStatus, triggeredBy: ID, limit: Int): [Task!]!

type

TaskType

Narrow to one task type, for example BINDER to watch document ingestion.

limit

Int

Cap the number of tasks returned (for example 1 for the most recent).

curl -X POST https://router.apps.filed.com/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_WORKSPACE_TOKEN" \
  -d '{
    "query": "query ClientTaskStatus($clientId: ID!, $type: TaskType) { me { ... on WorkspaceUser { workspace { clients(filters: { ids: [$clientId] }) { tasks(type: $type) { id status startedAt completedAt errorMessage subTasks { type status } } } } } } }",
    "variables": { "clientId": "018f9c2a-3d5f-7a10-b2c4-9e8d7f6a5b4c", "type": "BINDER" }
  }'

{
  "data": {
    "me": {
      "workspace": {
        "clients": [
          {
            "tasks": [
              {
                "id": "018f9c2b-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
                "status": "COMPLETED",
                "startedAt": "2026-07-04T09:15:00.000Z",
                "completedAt": "2026-07-04T09:17:42.000Z",
                "errorMessage": null,
                "subTasks": [
                  { "type": "CONVERT_DOCUMENTS", "status": "COMPLETED" },
                  { "type": "CLASSIFY_SUBDOCS", "status": "COMPLETED" },
                  { "type": "EXTRACT_SUBDOCS", "status": "COMPLETED" },
                  { "type": "EXPORT_AND_INDEX", "status": "COMPLETED" }
                ]
              }
            ]
          }
        ]
      }
    }
  }
}

Poll on an interval (for example every few seconds) until status is no longer RUNNING. COMPLETED means the work succeeded; FAILED means it did not, and errorMessage explains why. subTasks show which stage is currently running.

Task result

Every task carries a typed result. TaskResult is a union whose concrete type is determined by the task’s type. Select fields with an inline fragment on the member you expect, and read __typename to know which one you got.

union TaskResult =
    TaskUnknownResult
  | TaskTaxPrepResult
  | TaskTaxReviewResult
  | TaskTaxAdvisorResult

TaskUnknownResult

object

The fallback result, including for BINDER and CHAT tasks.

type TaskUnknownResult {
  message: String!
}

Show fields

message

String!

A human-readable description of the outcome.

TaskTaxPrepResult

object

Returned for TAX_PREP tasks: a summary plus document/form counts and the individual review items.

type TaskTaxPrepResult {
  taxYear: Int!
  returnType: ReturnType!
  summary: String!
  documentCount: Int!
  extractedFormCount: Int!
  reviewItemCount: Int!
  reviewItems: [TaxPrepReviewItem!]!
}

type TaxPrepReviewItem {
  severity: String!
  category: String!
  description: String!
}

Show fields

taxYear

Int!

The tax year.

returnType

ReturnType!

The return form (see ReturnType).

summary

String!

A summary of the tax prep result.

documentCount

Int!

Number of documents processed.

extractedFormCount

Int!

Number of forms extracted.

reviewItemCount

Int!

Number of review items produced.

reviewItems

[TaxPrepReviewItem!]!

The review items. Each has severity, category, and description (all String!).

TaskTaxReviewResult

object

Returned for TAX_REVIEW tasks: a summary plus issue breakdowns by severity and by form.

type TaskTaxReviewResult {
  taxYear: Int!
  returnType: ReturnType!
  summary: String!
  issueCountBySeverity: IssueCountBySeverity!
  issueCountByForm: [FormIssueCount!]!
}

type IssueCountBySeverity {
  critical: Int!
  high: Int!
  medium: Int!
  low: Int!
}

type FormIssueCount {
  form: String!
  count: Int!
}

Show fields

taxYear

Int!

The tax year.

returnType

ReturnType!

The return form.

summary

String!

A summary of the review result.

issueCountBySeverity

IssueCountBySeverity!

Issue counts by severity: critical, high, medium, low (all Int!).

issueCountByForm

[FormIssueCount!]!

Issue counts per form, each { form: String!, count: Int! }.

TaskTaxAdvisorResult

object

Returned for TAX_ADVISOR tasks: a summary plus strategy counts. The by* fields are JSON maps.

type TaskTaxAdvisorResult {
  taxYear: Int!
  returnType: ReturnType!
  summary: String!
  strategyTotal: Int!
  byDomain: JSON!
  bySavingsHorizon: JSON!
  estimatedSavingsCentsByHorizon: JSON!
}

Show fields

taxYear

Int!

The tax year.

returnType

ReturnType!

The return form.

summary

String!

A summary of the advisor result.

strategyTotal

Int!

Total number of strategies.

byDomain

JSON!

Strategy counts keyed by domain.

bySavingsHorizon

JSON!

Strategy counts keyed by savings horizon.

estimatedSavingsCentsByHorizon

JSON!

Estimated savings (in cents) keyed by horizon.

Because the members share taxYear, returnType, and summary, you can select those on each fragment and branch on __typename:

query TaskResult($clientId: ID!) {
  me {
    ... on WorkspaceUser {
      workspace {
        clients(filters: { ids: [$clientId] }) {
          tasks(type: TAX_PREP, limit: 1) {
            id
            status
            result {
              __typename
              ... on TaskTaxPrepResult {
                summary
                documentCount
                extractedFormCount
                reviewItems {
                  severity
                  category
                  description
                }
              }
              ... on TaskTaxReviewResult {
                summary
                issueCountBySeverity {
                  critical
                  high
                  medium
                  low
                }
                issueCountByForm {
                  form
                  count
                }
              }
              ... on TaskUnknownResult {
                message
              }
            }
          }
        }
      }
    }
  }
}

​The Task type

​Supporting types

​List tasks

​Arguments

​Check a single task’s status

​Task result

The `Task` type

Supporting types

List tasks

Arguments

Check a single task’s status

Task result