# Monitor extraction task status

Source: https://developer.avalara.com/products/returns/integration-guides/managed-returns/fcy1877890471345/

Guide: Avalara Managed Returns API (U.S. and Canada)

# Monitor extraction task status

Check the status of 1 or more background return extraction tasks with the `taskStatus` GraphQL query.

The `taskStatus` query returns the status of 1 or more background return extraction tasks. Use this query to track extraction tasks started by `grantAuthorityAccess` or `resumeAuthorityAccess`.

Key considerations:

-   **Polling cadence**: Poll this query repeatedly, for example, every 30 seconds, until no task remains in `InProgress` status. Background extractions can take several minutes, depending on the volume of historical filings.

-   **Terminal status handling**: The `status` field returns a string. Treat any value other than `InProgress` as a terminal state.

-   **Filing request IDs**: When a task completes with a status of `Success` or `SuccessWithMissing`, the `filingRequestIds` array contains the IDs of the generated filing requests. Pass these IDs to `approveFilingRequests` after you review the requests.

-   **Empty results**: A task with `Success` status can have an empty `filingRequestIds` array if the tax authority portal contains no historical filing data for that form code.

## View request

```
query TaskStatus($companyId: ID!, $taskIds: [ID!]!) {
  taskStatus(companyId: $companyId, taskIds: $taskIds) {
    taskId
    formCode
    status
    message
    dateCreated
    dateCompleted
    filingRequestIds
    generatedTaxFormCodes
  }
}
```

**Input variables**:

```
{
  "companyId": "1234567",
  "taskIds": [
    "aaaaaaaa-0000-4000-8000-000000000001",
    "aaaaaaaa-0000-4000-8000-000000000002"
  ]
}
```

Table 1. Input variable details

Argument

Type

Description

`companyId`

`ID!`

The unique identifier of the company that owns the tasks.

`taskIds`

`[ID!]!`

The array of task IDs to check. Get these IDs from the `tasks` array returned by `grantAuthorityAccess` or `resumeAuthorityAccess`.

## View response

```
{
  "data": {
    "taskStatus": [
      {
        "taskId": "aaaaaaaa-0000-4000-8000-000000000001",
        "formCode": "USAL2100",
        "status": "InProgress",
        "message": null,
        "dateCreated": "2026-01-15T09:13:30.9832215",
        "dateCompleted": null,
        "filingRequestIds": []
        “generatedTaxFormCodes”: []
      },
      {
        "taskId": "aaaaaaaa-0000-4000-8000-000000000002",
        "formCode": "USALSU2610",
        "status": "Success",
        "message": null,
        "dateCreated": "2026-01-15T09:23:57.394736",
        "dateCompleted": "2026-01-15T10:00:10.036327",
        "filingRequestIds": ["200001"]
        "generatedTaxFormCodes": ["USALSU2610"]
      }
    ]
  }
}
```

**Response field descriptions**:

Response field

Description

`taskId`

The unique identifier for the extraction task.

`formCode`

The tax form code for which the task extracts data.

`status`

The current lifecycle status of the task.

`message`

A readable note about the task. For a failed task, it describes what went wrong. It’s `null` when there’s no message.

`dateCreated`

When the task was created, as an ISO 8601 date-time value.

`dateCompleted`

When the task finished. It's `null` while the task is `InProgress`.

`filingRequestIds`

The filing requests created by the task. This array is empty until the task reaches `Success` or `SuccessWithMissing`. Pass these IDs to `approveFilingRequests` after review.

`generatedTaxFormCodes`

The tax form codes of the filing requests created by the task. This array is empty until the task reaches `Success` or `SuccessWithMissing`.

**Task status values**:

Value

Meaning

`InProgress`

The extraction is running.

`Success`

The extraction finished successfully.

`SuccessWithMissing`

The extraction finished, but some data is missing.

`Failed`

The extraction failed.

`NotApplicable`

The task doesn’t apply, so nothing is extracted.

## Next steps

If an onboarding session is interrupted, see Query saved authority accounts and Resume authority onboarding session. To approve the generated filing requests, see [Approve extracted filing requests](/managed-returns/why7129607850668/ "Approve extracted pending filing requests and convert them into active filing calendars by using the approveFilingRequests GraphQL mutation.").