> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apps.filed.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get job work artifact status

> Query artifact status for job works via connection

Retrieve the status of artifacts attached to job works. This allows you to monitor file processing progress, check upload status, and track the overall state of documents associated with tax preparations.

```graphql theme={null}
query GetJobWorkArtifactStatus($workspaceId: ID!, $connectionId: ID!, $jobWorkFilters: JobWorkFilters) {
  me {
    workspaces(filters: { ids: [$workspaceId] }) {
      id
      connections(filters: { ids: [$connectionId] }) {
        id
        jobWorks(filters: $jobWorkFilters) {
          id
          work {
            id
            name
            externalId
          }
          jobWorkArtifacts {
            id
            createdAt
            updatedAt
            workspaceId
            artifactId
            connectionJobId
            jobWorkId
            workArtifact {
              id
              externalId
              createdAt
              updatedAt
              workId
              connectionId
              name
              type
              status
              uploadedUrl
              metadata
            }
          }
        }
      }
    }
  }
}
```

## Arguments

<ParamField path="connectionId" type="ID!" required>
  The ID of the provider connection. Use this to scope the query to artifacts from a specific connection.
</ParamField>

<ParamField path="jobWorkFilters" type="JobWorkFilters">
  Filters to identify which job works to retrieve artifacts for.

  <Expandable title="JobWorkFilters">
    <ParamField path="jobWorkFilters.ids" type="[ID!]">
      Filter by specific job work IDs. Returns artifacts only for the specified job works.
    </ParamField>

    <ParamField path="jobWorkFilters.connectionJobIds" type="[ID!]">
      Filter by connection job IDs. Returns artifacts for all job works in the specified connection jobs.
    </ParamField>

    <ParamField path="jobWorkFilters.workIds" type="[ID!]">
      Filter by work IDs. Returns artifacts for all job works associated with the specified works.
    </ParamField>
  </Expandable>
</ParamField>

## Returns

### JobArtifact

<ResponseField name="id" type="ID!">
  The unique identifier of the job artifact.
</ResponseField>

<ResponseField name="createdAt" type="Date!">
  Timestamp when the job artifact was created.
</ResponseField>

<ResponseField name="updatedAt" type="Date!">
  Timestamp when the job artifact was last updated.
</ResponseField>

<ResponseField name="workspaceId" type="ID!">
  The workspace ID this job artifact belongs to.
</ResponseField>

<ResponseField name="artifactId" type="ID!">
  Reference to the underlying work artifact.
</ResponseField>

<ResponseField name="connectionJobId" type="ID!">
  The connection job ID this artifact is associated with.
</ResponseField>

<ResponseField name="jobWorkId" type="ID!">
  The job work ID this artifact is attached to.
</ResponseField>

<ResponseField name="workArtifact" type="WorkArtifact!">
  The underlying work artifact with detailed status information.

  <Expandable title="WorkArtifact fields">
    <ResponseField name="workArtifact.id" type="ID!">
      The unique identifier of the work artifact.
    </ResponseField>

    <ResponseField name="workArtifact.externalId" type="String!">
      Your platform's unique identifier for this file/artifact.
    </ResponseField>

    <ResponseField name="workArtifact.createdAt" type="Date!">
      Timestamp when the artifact was created.
    </ResponseField>

    <ResponseField name="workArtifact.updatedAt" type="Date!">
      Timestamp when the artifact was last updated.
    </ResponseField>

    <ResponseField name="workArtifact.workId" type="ID!">
      The work ID this artifact belongs to.
    </ResponseField>

    <ResponseField name="workArtifact.connectionId" type="ID!">
      The connection ID this artifact belongs to.
    </ResponseField>

    <ResponseField name="workArtifact.name" type="String!">
      The name of the artifact (e.g., "W-2 Form", "1099-INT").
    </ResponseField>

    <ResponseField name="workArtifact.type" type="String!">
      The type/category of the artifact (e.g., "w2", "1099", "receipt").
    </ResponseField>

    <ResponseField name="workArtifact.status" type="String!">
      The current processing status of the artifact. See [Artifact Status Reference](#artifact-status-reference) for details.
    </ResponseField>

    <ResponseField name="workArtifact.uploadedUrl" type="String">
      The URL where the artifact file was uploaded, if available.
    </ResponseField>

    <ResponseField name="workArtifact.metadata" type="JSON">
      Additional metadata about the artifact (e.g., file size, mime type, processing details).
    </ResponseField>
  </Expandable>
</ResponseField>

## Example: Get Artifact Status by Job Work ID

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://gateway.filed.com/graphql \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <accessToken>" \
    -H "source-platform: my-sample-platform" \
    -d '{
      "query": "query GetJobWorkArtifactStatus($workspaceId: ID!, $connectionId: ID!, $jobWorkFilters: JobWorkFilters) { me { workspaces(filters: { ids: [$workspaceId] }) { id connections(filters: { ids: [$connectionId] }) { id jobWorks(filters: $jobWorkFilters) { id work { id name externalId } jobWorkArtifacts { id createdAt updatedAt artifactId connectionJobId jobWorkId workArtifact { id externalId name type status uploadedUrl metadata } } } } } } }",
      "variables": {
        "workspaceId": "workspace_123456",
        "connectionId": "connection_789",
        "jobWorkFilters": {
          "ids": ["job_work_456"]
        }
      }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "data": {
      "me": {
        "workspaces": [
          {
            "id": "workspace_123456",
            "connections": [
          {
            "id": "connection_789",
            "jobWorks": [
              {
                "id": "job_work_456",
                "work": {
                  "id": "work_789",
                  "name": "John Smith - 2024 Tax Return",
                  "externalId": "client-12345"
                },
                "jobWorkArtifacts": [
                  {
                    "id": "job_artifact_001",
                    "createdAt": "2024-01-15T10:40:00Z",
                    "updatedAt": "2024-01-15T10:42:00Z",
                    "artifactId": "artifact_001",
                    "connectionJobId": "job_123456",
                    "jobWorkId": "job_work_456",
                    "workArtifact": {
                      "id": "artifact_001",
                      "externalId": "file-w2-001",
                      "name": "W-2 Form 2024",
                      "type": "w2",
                      "status": "completed",
                      "uploadedUrl": "https://storage.filed.com/artifacts/artifact_001.pdf",
                      "metadata": {
                        "fileSize": 245678,
                        "mimeType": "application/pdf",
                        "pages": 2
                      }
                    }
                  },
                  {
                    "id": "job_artifact_002",
                    "createdAt": "2024-01-15T10:40:05Z",
                    "updatedAt": "2024-01-15T10:40:05Z",
                    "artifactId": "artifact_002",
                    "connectionJobId": "job_123456",
                    "jobWorkId": "job_work_456",
                    "workArtifact": {
                      "id": "artifact_002",
                      "externalId": "file-1099-001",
                      "name": "1099-INT Statement",
                      "type": "1099",
                      "status": "pending",
                      "uploadedUrl": null,
                      "metadata": {
                        "fileSize": 189234,
                        "mimeType": "application/pdf"
                      }
                    }
                  }
                ]
              }
            ]
          }
        ]
          }
        ]
      }
    }
  }
  ```
</ResponseExample>

## Example: Monitor All Artifacts for a Connection Job

Track the status of all artifacts across all job works in a connection job:

```graphql theme={null}
query MonitorConnectionJobArtifacts($workspaceId: ID!, $connectionId: ID!, $connectionJobId: ID!) {
  me {
    workspaces(filters: { ids: [$workspaceId] }) {
      id
      connections(filters: { ids: [$connectionId] }) {
        id
        jobWorks(filters: { connectionJobIds: [$connectionJobId] }) {
          id
          work {
            name
            externalId
          }
          jobWorkArtifacts {
            id
            workArtifact {
              name
              type
              status
              externalId
            }
          }
        }
      }
    }
  }
}
```

## Artifact Status Reference

Work artifacts have the following statuses that indicate their processing state:

<ResponseField name="pending" type="Status">
  **Initial state** — The artifact has been created but has not yet been processed. This is the default status when an artifact is first created via `createJobWorkArtifacts`.

  When you see this status:

  * The artifact record exists in Filed
  * File fetching/processing has not started yet
  * The file URL provided is queued for download
</ResponseField>

<ResponseField name="completed" type="Status">
  **Success state** — The artifact has been successfully processed. The file has been fetched from the provided URL and is now available in Filed.

  When you see this status:

  * The file was successfully downloaded from the source URL
  * The artifact is ready for use in tax preparation workflows
  * The `uploadedUrl` field will contain the Filed storage URL
</ResponseField>

<ResponseField name="failed" type="Status">
  **Error state** — The artifact processing failed. This typically occurs when the file could not be fetched or processed.

  Common causes:

  * The source URL is inaccessible or returns an error
  * The file format is unsupported or corrupted
  * Authentication to the source URL failed
  * Network timeout during file download

  Check the `metadata` field for error details.
</ResponseField>

<ResponseField name="cancelled" type="Status">
  **Terminated state** — The artifact was explicitly cancelled. This occurs when the artifact processing was stopped before completion.

  When you see this status:

  * The artifact will not be processed further
  * This may occur if the parent job was cancelled
  * The artifact can be recreated if needed
</ResponseField>

### Status Workflow

```
                              ┌───────────┐
                         ┌───▶│ completed │
                         │    └───────────┘
┌─────────┐              │
│ pending │──── process ─┼───▶┌────────┐
└─────────┘              │    │ failed │
                         │    └────────┘
                         │
                         └───▶┌───────────┐
                              │ cancelled │
                              └───────────┘
```

<Note>
  Artifacts start in `pending` status and transition to a terminal state (`completed`, `failed`, or `cancelled`) after processing. Poll periodically to track progress.
</Note>

## Work Status Reference

The parent `Work` entity (accessible via `jobWork.work.status`) has its own status values:

<ResponseField name="pending" type="Work Status">
  **Initial state** — The work has been created but not yet imported into Filed's tax preparation system.
</ResponseField>

<ResponseField name="imported" type="Work Status">
  **Success state** — The work has been successfully imported and is available for tax preparation.
</ResponseField>

<ResponseField name="error" type="Work Status">
  **Error state** — An error occurred during import processing.
</ResponseField>

<ResponseField name="deleted" type="Work Status">
  **Removed state** — The work has been deleted and is no longer active.
</ResponseField>

## Best Practices

1. **Batch status checks**: Query multiple job works at once rather than making individual requests for each artifact.

2. **Use filters efficiently**: When monitoring a specific import, use `connectionJobIds` filter to get all artifacts for that batch.

3. **Handle failures gracefully**: Check for `failed` status and review metadata for error details.

4. **Correlate with external IDs**: Use `workArtifact.externalId` to match artifacts back to your platform's file records.

## Troubleshooting

**Problem**: Artifact status stuck on `pending`

**Solutions**:

* Verify the file URL provided in `createJobWorkArtifacts` is accessible
* Check that the URL returns a valid file (not an error page)
* Ensure the file format is supported
* Review connection credentials if the file requires authentication
* Trigger the import process via [initiateTaxPrepsImport](/legacy/apis/endpoint/initiate-tax-preps-import) if not already done

**Problem**: Artifact status shows `failed`

**Solutions**:

* Check the `metadata` field for error details
* Verify the file URL is still valid and accessible
* Ensure the file is not corrupted or empty
* Try re-creating the artifact with a fresh URL
* Common causes: URL timeout, 404 errors, invalid file format

**Problem**: Artifact status shows `cancelled`

**Solutions**:

* Check if the parent connection job was cancelled
* Recreate the artifact if processing is still needed
* Verify the job work and connection job are in valid states

**Problem**: `uploadedUrl` is null

**Solutions**:

* Check the `status` field — URL is only populated when status is `completed`
* For `pending` status, wait for processing to complete
* For `failed` status, the file was not successfully fetched