Arguments
The ID of the provider connection. Use this to scope the query to artifacts from a specific connection.
Returns
JobArtifact
Example: Get Artifact Status by Job Work ID
Example: Monitor All Artifacts for a Connection Job
Track the status of all artifacts across all job works in a connection job:Artifact Status Reference
Work artifacts have the following statuses that indicate their processing state: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
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
uploadedUrlfield will contain the Filed storage URL
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
metadata field for error details.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
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 parentWork entity (accessible via jobWork.work.status) has its own status values:
Initial state — The work has been created but not yet imported into Filed’s tax preparation system.
Success state — The work has been successfully imported and is available for tax preparation.
Best Practices
- Batch status checks: Query multiple job works at once rather than making individual requests for each artifact.
-
Use filters efficiently: When monitoring a specific import, use
connectionJobIdsfilter to get all artifacts for that batch. -
Handle failures gracefully: Check for
failedstatus and review metadata for error details. -
Correlate with external IDs: Use
workArtifact.externalIdto match artifacts back to your platform’s file records.
Troubleshooting
Problem: Artifact status stuck onpending
Solutions:
- Verify the file URL provided in
createJobWorkArtifactsis 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
failed
Solutions:
- Check the
metadatafield 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
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
uploadedUrl is null
Solutions:
- Check the
statusfield — URL is only populated when status iscompleted - For
pendingstatus, wait for processing to complete - For
failedstatus, the file was not successfully fetched