Skip to main content
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. 
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

​
connectionId
ID!
required
The ID of the provider connection. Use this to scope the query to artifacts from a specific connection.
​
jobWorkFilters
JobWorkFilters
Filters to identify which job works to retrieve artifacts for.

​
Returns

​
JobArtifact

​
id
ID!
The unique identifier of the job artifact.
​
createdAt
Date!
Timestamp when the job artifact was created.
​
updatedAt
Date!
Timestamp when the job artifact was last updated.
​
workspaceId
ID!
The workspace ID this job artifact belongs to.
​
artifactId
ID!
Reference to the underlying work artifact.
​
connectionJobId
ID!
The connection job ID this artifact is associated with.
​
jobWorkId
ID!
The job work ID this artifact is attached to.
​
workArtifact
WorkArtifact!
The underlying work artifact with detailed status information.

​
Example: Get Artifact Status by Job Work ID

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"]
      }
    }
  }'

{
  "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"
                    }
                  }
                }
              ]
            }
          ]
        }
      ]
        }
      ]
    }
  }
}

​
Example: Monitor All Artifacts for a Connection Job

Track the status of all artifacts across all job works in a connection job: 
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:
​
pending
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
​
completed
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
​
failed
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.
​
cancelled
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

​
Status Workflow

                              ┌───────────┐
                         ┌───▶│ completed │
                         │    └───────────┘
┌─────────┐              │
│ pending │──── process ─┼───▶┌────────┐
└─────────┘              │    │ failed │
                         │    └────────┘
                         │
                         └───▶┌───────────┐
                              │ cancelled │
                              └───────────┘
Artifacts start in pending status and transition to a terminal state (completed, failed, or cancelled) after processing. Poll periodically to track progress.

​
Work Status Reference

The parent Work entity (accessible via jobWork.work.status) has its own status values:
​
pending
Work Status
Initial state — The work has been created but not yet imported into Filed’s tax preparation system.
​
imported
Work Status
Success state — The work has been successfully imported and is available for tax preparation.
​
error
Work Status
Error state — An error occurred during import processing.
​
deleted
Work Status
Removed state — The work has been deleted and is no longer active.

​
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 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