> ## 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 works

> Query job works by ID via a provider connection

Retrieve job works associated with a provider connection. Job works represent individual client/tax preparation entries that were created as part of an import job. You can filter by specific job work IDs, connection job IDs, or work IDs.

```graphql theme={null}
query GetJobWorks($workspaceId: ID!, $connectionId: ID!, $filters: JobWorkFilters, $sortBy: SortBy, $offset: Int, $limit: Int) {
  me {
    workspaces(filters: { ids: [$workspaceId] }) {
      id
      connections(filters: { ids: [$connectionId] }) {
        id
        jobWorks(filters: $filters, sortBy: $sortBy, offset: $offset, limit: $limit) {
          id
          createdAt
          updatedAt
          workspaceId
          workId
          connectionJobId
          work {
            id
            name
            externalId
            status
            tag
          }
          jobWorkArtifacts {
            id
            artifactId
            workArtifact {
              id
              externalId
              name
              type
              status
            }
          }
        }
      }
    }
  }
}
```

## Arguments

<ParamField path="connectionId" type="ID!" required>
  The ID of the provider connection to query job works from. This is the connection ID returned from [startProviderConnection](/legacy/apis/endpoint/start-provider-connection).
</ParamField>

<ParamField path="filters" type="JobWorkFilters">
  Optional filters to narrow down the job works returned.

  <Expandable title="JobWorkFilters">
    <ParamField path="filters.ids" type="[ID!]">
      Filter by specific job work IDs. Use this to retrieve one or more specific job works by their unique identifiers.
    </ParamField>

    <ParamField path="filters.connectionJobIds" type="[ID!]">
      Filter by connection job IDs. Returns all job works that belong to the specified connection jobs.
    </ParamField>

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

<ParamField path="sortBy" type="SortBy">
  Optional sorting configuration.

  <Expandable title="SortBy">
    <ParamField path="sortBy.field" type="String!">
      Field to sort by (e.g., "createdAt", "updatedAt").
    </ParamField>

    <ParamField path="sortBy.order" type="SortByOrder!">
      Sort direction: `ASC` for ascending or `DESC` for descending.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="offset" type="Int">
  Number of records to skip for pagination. Defaults to 0.
</ParamField>

<ParamField path="limit" type="Int">
  Maximum number of records to return. Use with offset for pagination.
</ParamField>

## Returns

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

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

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

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

<ResponseField name="workId" type="ID!">
  The work ID this job work references.
</ResponseField>

<ResponseField name="connectionJobId" type="ID!">
  The connection job ID this job work belongs to.
</ResponseField>

<ResponseField name="work" type="Work!">
  The associated work (client/tax preparation) details.

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

    <ResponseField name="work.name" type="String!">
      The name of the work (typically the client name).
    </ResponseField>

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

    <ResponseField name="work.status" type="String!">
      The current status of the work:

      * `pending` - Work created but not yet imported
      * `imported` - Work successfully imported into Filed
      * `error` - An error occurred during import
      * `deleted` - Work has been removed
    </ResponseField>

    <ResponseField name="work.tag" type="String">
      Optional tag associated with the work.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="jobWorkArtifacts" type="[JobArtifact!]!">
  List of artifacts attached to this job work. See [get-job-work-artifacts](/legacy/apis/endpoint/get-job-work-artifacts) for detailed artifact status information.
</ResponseField>

## Example: Get Job Work by 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 GetJobWorks($workspaceId: ID!, $connectionId: ID!, $filters: JobWorkFilters) { me { workspaces(filters: { ids: [$workspaceId] }) { id connections(filters: { ids: [$connectionId] }) { id jobWorks(filters: $filters) { id createdAt updatedAt workspaceId workId connectionJobId work { id name externalId status tag } jobWorkArtifacts { id artifactId workArtifact { id externalId name type status } } } } } } }",
      "variables": {
        "workspaceId": "workspace_123456",
        "connectionId": "connection_789",
        "filters": {
          "ids": ["job_work_456"]
        }
      }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "data": {
      "me": {
        "workspaces": [
          {
            "id": "workspace_123456",
            "connections": [
          {
            "id": "connection_789",
            "jobWorks": [
              {
                "id": "job_work_456",
                "createdAt": "2024-01-15T10:35:00Z",
                "updatedAt": "2024-01-15T10:40:00Z",
                "workspaceId": "workspace_123456",
                "workId": "work_789",
                "connectionJobId": "job_123456",
                "work": {
                  "id": "work_789",
                  "name": "John Smith - 2024 Tax Return",
                  "externalId": "client-12345",
                  "status": "pending",
                  "tag": "individual"
                },
                "jobWorkArtifacts": [
                  {
                    "id": "job_artifact_001",
                    "artifactId": "artifact_001",
                    "workArtifact": {
                      "id": "artifact_001",
                      "externalId": "file-w2-001",
                      "name": "W-2 Form 2024",
                      "type": "w2",
                      "status": "completed"
                    }
                  }
                ]
              }
            ]
          }
        ]
          }
        ]
      }
    }
  }
  ```
</ResponseExample>

## Example: Get All Job Works for a Connection Job

Query all job works that belong to a specific connection job:

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

<Note>
  The `jobWorks` field on a connection returns all job works across all connection jobs for that connection. Use the `connectionJobIds` filter to narrow down to a specific import batch.
</Note>

## Troubleshooting

**Problem**: No job works returned despite creating them

**Solutions**:

* Verify you're querying the correct connection ID
* Check that the job work IDs in your filter are correct
* Ensure the job works were successfully created (check for errors in the `createJobWorks` response)
* Confirm you have access to the workspace containing the connection

**Problem**: Missing artifact information

**Solutions**:

* Artifacts may not have been created yet - verify with `createJobWorkArtifacts`
* Include the `jobWorkArtifacts` field in your query to fetch artifact details
* Check artifact status to see if files are still being processed