Reports

Retrieve export

Read an existing API export. Requires API access: Manage and Reports: View. Any authorized company teammate can retrieve it. Other companies, unknown IDs, raw database IDs, and exports created through the web UI return 404. Department exports also require the feature. GET never generates reports, dispatches workers, or marks a file downloaded. Status is pending, processing, succeeded, or failed. A file is exposed only after successful worker completion, final permission checks, and attachment. Fresh links are available for 30 days after completed_at. At or after that cutoff, status remains succeeded but file is null and error is null, including on an idempotent POST replay. The stored file is retained. Request a new export with a new Idempotency-Key to generate another report from the current books. Within that window, signed download URLs request expiry seven days after retrieval; retrieve this resource again for a fresh URL. Previously issued links keep their original expiry, which can extend beyond the 30-day regeneration cutoff. Signing credential expiry or storage policies can invalidate a link sooner. Link expiry does not delete the file. A download started before expiry can finish afterward; restarting or requesting further byte ranges after expiry requires a fresh link. Download URLs are bearer links and remain usable until expiration even if API access changes. Both responses use Cache-Control no-store. Failure details contain safe codes, never stack traces. The existing API request log stores export ID, status, and whether a link was issued, alongside caller and request time. Pending/failed polls and HEAD probes do not count as link issuance. Actual S3 downloads are not tracked. started_at records the first generation attempt and can remain null when access is revoked before generation; generation_duration_ms is the cumulative time spent in generation attempts, excluding queue and retry waits.

GET

reports

exports

{id}

Retrieve export

curl --request GET \
  --url https://app.finta.com/api/v1/reports/exports/{id} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://app.finta.com/api/v1/reports/exports/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.finta.com/api/v1/reports/exports/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://app.finta.com/api/v1/reports/exports/{id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://app.finta.com/api/v1/reports/exports/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "object": "report_export",
  "report_type": "income_statement",
  "format": "pdf",
  "start_date": "2023-12-25",
  "end_date": "2023-12-25",
  "group_by": {
    "period": "month",
    "rows": "category"
  },
  "status": "pending",
  "created": 123,
  "started_at": 123,
  "completed_at": 123,
  "generation_duration_ms": 1,
  "file": {
    "filename": "<string>",
    "content_type": "application/pdf",
    "size": 1,
    "download_url": "<string>",
    "expires_at": 123
  },
  "error": {
    "code": "access_revoked",
    "message": "<string>"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "<string>",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#invalid_api_key",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "<string>",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#invalid_api_key",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "<string>",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#invalid_api_key",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "<string>",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#invalid_api_key",
    "param": "<string>"
  }
}

Authorizations

Authorization

string

header

required

API key prefixed with finta_

Path Parameters

string

required

Export ID from creation, starting with export_.

Response

Current export status and result.

string

required

Pattern: ^export_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

object

enum<string>

required

Available options:

report_export

report_type

enum<string>

required

Available options:

income_statement,

balance_sheet,

cash_flow

format

enum<string>

required

Available options:

pdf,

csv,

xlsx

start_date

string<date>

required

end_date

string<date>

required

group_by

object

required

Omitted members default to month for period and category for rows. Department rows are supported only for income statements and require the feature.

Show child attributes

status

enum<string>

required

pending awaits generation; processing includes generation and retry waits; succeeded exposes the retained file after final access checks while within 30 days of completed_at, then file is null; failed is terminal and requires a new key for a new job. An HTTP 200 retrieval may still carry failed status.

Available options:

pending,

processing,

succeeded,

failed

created

integer

required

started_at

integer | null

required

Unix timestamp of the first generation attempt. Null until generation starts, including a terminal failure when access is revoked before generation.

completed_at

integer | null

required

Unix timestamp of terminal completion, whether succeeded or failed. Null while unfinished.

generation_duration_ms

integer | null

required

Cumulative generation attempt duration in milliseconds, including upload but excluding queue and retry wait time. Null until an attempt finishes.

Required range: x >= 0

file

object | null

required

Available only for succeeded exports before completed_at plus 30 days. Null at or after that cutoff, including on idempotent POST replay; status remains succeeded and error remains null. Within the window, refresh download_url by retrieving the export again. Already-issued links keep their original expiry; neither link expiry nor the regeneration cutoff removes the stored file.

Show child attributes

error

object | null

required

Safe job failure details, present only when status is failed. This is distinct from an HTTP error envelope. New submissions with unconfirmed dispatch return HTTP 503 and retain a pending job, rather than setting enqueue_failed.

Show child attributes

Retrieve export

curl --request GET \
  --url https://app.finta.com/api/v1/reports/exports/{id} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://app.finta.com/api/v1/reports/exports/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.finta.com/api/v1/reports/exports/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://app.finta.com/api/v1/reports/exports/{id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://app.finta.com/api/v1/reports/exports/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "object": "report_export",
  "report_type": "income_statement",
  "format": "pdf",
  "start_date": "2023-12-25",
  "end_date": "2023-12-25",
  "group_by": {
    "period": "month",
    "rows": "category"
  },
  "status": "pending",
  "created": 123,
  "started_at": 123,
  "completed_at": 123,
  "generation_duration_ms": 1,
  "file": {
    "filename": "<string>",
    "content_type": "application/pdf",
    "size": 1,
    "download_url": "<string>",
    "expires_at": 123
  },
  "error": {
    "code": "access_revoked",
    "message": "<string>"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "<string>",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#invalid_api_key",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "<string>",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#invalid_api_key",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "<string>",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#invalid_api_key",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "<string>",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#invalid_api_key",
    "param": "<string>"
  }
}

API Reference

Taxes

Files

Company

Team

Categories

Rules

Departments

Integrations

Aggregations

Transactions

Forms

Journal Entries

Invoices

Parties

Reports

Feedback

Tax Credits

Retrieve export

Authorizations

Path Parameters

Response