---
title: "List tax return generation requests"
method: GET
path: "/internal/api/tax-return-generation-requests"
tags: ["Tax Return Generation"]
---

# List tax return generation requests

`GET /internal/api/tax-return-generation-requests`

## Request

- Base URL: `https://api.signalshq.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.signalshq.io/internal/api/tax-return-generation-requests`
- Auth: OAuth 2
  - Password
  - Token URL: `/auth/login`

Paginated list of tax returns that have at least one workpaper evaluation job, for all clients in the tenant. Filter by tax year, latest job status, client id, or client name search.

## Query parameters

- `page` integer: Page number (1-based)
- `page_size` integer: Items per page (max 100)
- `sort_by` string: Sort field: last_generation_at, first_generation_at, client_name, tax_year
- `sort_order` string: asc or desc
- `tax_year` integer, nullable: Filter by tax year
- `latest_job_status` string, nullable: Comma-separated latest job statuses: PENDING, RUNNING, COMPLETED, FAILED
- `client_id` string, uuid, nullable: Filter by client id
- `search` string, nullable: Case-insensitive partial match on client full name (min 2 chars when set)

## Response `200`

Successful Response

- TaxReturnGenerationRequestListResponse: Paginated list of tax return generation requests for the tenant.
  - `data` TaxReturnGenerationRequestItem[]
    - `tax_return_id` string, uuid, required: Tax return id; use with workpaper status and GET workpaper.
    - `client_id` string, uuid, required: Client id
    - `client_name` string, required: Client full name
    - `client_readable_id` string, required: Human-readable client id (e.g. AT-12345)
    - `tax_year` integer, required: Tax year
    - `return_type` 'ORIGINAL' | 'AMENDED', required: Return type: ORIGINAL | AMENDED. DB: core_schema.tax_return_type_enum.
    - `return_status` 'DRAFT' | 'REVIEW' | 'FILED' | 'ACCEPTED', required: Tax return lifecycle. DB: core_schema.tax_return_status_enum.
    - `workpaper_pdf_storage_key` string, nullable: Full workpaper PDF storage key; same as GET workpaper workpaper_pdf_storage_key.
    - `workpaper_dirty` boolean, required: True if return data changed since last successful generation (stale workpaper).
    - `first_generation_at` string, date-time, required: When the first evaluation job was created for this tax return.
    - `last_generation_at` string, date-time, required: Latest generation activity: job completed_at if set, else job updated_at.
    - `job_id` string, uuid, required: Latest evaluation job id
    - `job_status` 'PENDING' | 'RUNNING' | 'COMPLETED' | 'FAILED', required: Job lifecycle. DB: workpaper_regeneration_job_status_enum. API adds IDLE in core.
    - `job_last_outcome` 'COMPLETE' | 'PARTIAL' | 'ERROR': Workpaper/form outcome. DB: core_schema.workpaper_status_outcome_enum.
    - `job_completed_at` string, date-time, nullable: When the latest job finished (COMPLETED or FAILED).
    - `job_error_message` string, nullable: Error message when latest job status is FAILED.
    - `display_status` string, required: Short UI label derived from job_status (e.g. Pending, Running, Completed, Failed).
  - `meta` AppSchemasCommonPaginationPaginationMeta, required
    - `page` integer, required: Current page number
    - `page_size` integer, required: Number of items per page
    - `total_count` integer, required: Total number of items
    - `total_pages` integer, required: Total number of pages
    - `total` integer, required: Alias for total_count for backward compatibility

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/signalshq/apis/signals-api.md) - [All operations](https://skmtc.dev/signalshq/apis/signals-api/llms.txt) - [OpenAPI document](https://skmtc.dev/signalshq/apis/signals-api/revisions/2c22af3b5576?raw)