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

# Report exports

> Generate PDF, CSV, and XLSX reports, check their status, and retrieve download links

After [connecting Finta](/docs/mcp/introduction#connect), ask your assistant to export
an income statement, balance sheet, cash flow statement, or GAAP P\&L.

| Tool | Purpose |
| - | - |
| `create_report_export` | Submit an export and immediately return its ID and status. |
| `get_report_export` | Check that export once, or retrieve a fresh download link after it succeeds. |

Both tools require **API access: Manage** and **Reports: View** in the connected
company. OAuth `finta:read` is sufficient; exporting creates a file without editing
the books. Permissions are checked on every call. Company and filename are inferred
from the connection, and an export ID cannot select a different company.

The existing `get_income_statement`, `get_balance_sheet`, and `get_cash_flow`
tools return financial data directly. Use the export tools when you need a file.

## Create an export

The examples show the tool name and arguments your MCP client sends. Your client
handles OAuth and the MCP transport.

```json theme={null}
{
  "name": "create_report_export",
  "arguments": {
    "report_type": "income_statement",
    "start_date": "2026-01-01",
    "end_date": "2026-03-31",
    "format": "pdf",
    "group_by": { "period": "month", "rows": "category" },
    "idempotency_key": "income-statement-q1-2026-request-1"
  }
}
```

| Argument | Options and defaults |
| - | - |
| `report_type` | Required: `income_statement`, `balance_sheet`, or `cash_flow`. |
| `start_date`, `end_date` | Required inclusive dates, `YYYY-MM-DD`, with the start on or before the end. Balance sheets also need both dates. |
| `format` | `pdf` (default), `csv`, or `xlsx`. |
| `group_by.period` | `month` (default), `quarter`, or `year`; time columns follow company calendar/fiscal settings. |
| `group_by.rows` | `category` (default), or `department` for the GAAP income statement. Department rows require `income_statement` and the departments feature. |
| `idempotency_key` | Required nonblank string of 1–255 characters, unique to this export request. |

Ranges may span at most **120 calendar months**, counting both boundary months.
PDFs additionally support at most **13 displayed periods**. For more columns,
shorten the range, use coarser grouping, or select CSV/XLSX. Balance-sheet periods
show cumulative balances through each cutoff, including history before the start.
Unknown API fields, including `email_on_completion`, are refused.

Creation returns a `report_export` immediately, with its `export_` ID, status,
parameters, timestamps, generation duration, and nullable `file` and `error`.
The assistant should retain that ID and use the retrieval tool to check it.

### Retry safely

Generate a key once per requested export and keep it across retries. The tool sends
`idempotency_key` as the API's `Idempotency-Key` header, not as a report field.
The same key and normalized inputs return the original export. Different inputs
under that key return `idempotency_key_conflict`; changing the key creates a new job.

If submission times out or queueing cannot be confirmed, retry the same key and
inputs. Once an ID is known, poll it instead of submitting again. A terminal failure
keeps its ID and key: fix the cause and use a new key if a new export is wanted.

The worker reads the books during generation. An existing export remains the
original file; to export updated books, use a new key.

## Poll the export

```json theme={null}
{
  "name": "get_report_export",
  "arguments": {
    "export_id": "export_6c081eba-cc9e-42c7-ae44-20e3eb18d8fb"
  }
}
```

Each call makes one status check and returns immediately. The assistant can wait
between calls, for example 2, 5, 10, then 30 seconds, with a bounded number of
checks rather than a tight loop. These intervals are guidance, not a completion
estimate. Each create or retrieve call counts toward the company's
[MCP allowance](/docs/mcp/introduction#limits); the inner API request does not also
consume the API allowance.

| Status | Next step |
| - | - |
| `pending`, `processing` | Wait before checking again; `file` is null. |
| `succeeded` | Download `file.download_url` if present. If file is null, the 30-day link window has ended; stop polling. |
| `failed` | Stop polling and explain `error.code` and `error.message`; `file` is null. |

A successfully retrieved export can have `status: "failed"`. Check the status and
error fields instead of assuming a successful tool call means generation succeeded.
There is no automatic completion notification in this flow.

## Download or refresh the link

On success, `file` contains `filename`, `content_type`, `size`, `download_url`,
and `expires_at`. The assistant uses its host's download/file tools to fetch the
URL and save the file, ideally using the returned filename. If the host cannot
download files, the assistant can give you the link instead. The MCP tool itself
does not save a file on your computer; the assistant should confirm a download
only after its host reports that saving succeeded.

Fresh links are available only before completed\_at plus 30 days (2,592,000 seconds). At or after that cutoff, retrieval and creation replays still return succeeded, with file/error null. The stored file is retained. A new export with a new key generates another report from current books; it does not restore the old snapshot.

Within that window, successful retrieval requests a fresh link expiring seven days from that
retrieval. Credentials or storage policies can invalidate it sooner. Retrieve
the same export again for a fresh link before the cutoff; this does not regenerate the report. Previously issued links keep their original expiry, even beyond the cutoff.
Export records and files have no automatic age-based cleanup in the application.

Five unfinished API exports are allowed per company, including those queued or
waiting to retry. At capacity, creation returns `report_export_limit_exceeded`;
polling and replay remain available, subject to normal limits. For other refusal
and recovery details, see [Report Exports](/docs/api-reference/report-exports) and
[Errors](/docs/api-reference/errors).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.