# List filing periods > The filing_periods.list operation: GET /api/v1/filing_periods in the REST API and the filing_periods_list tool in the MCP server. Lists the legal entity's filing periods in the mode of the request, newest first. Ownrecord creates a period for every regime the entity is registered in (or in a grace period for), from the regime's filing rules: its frequency and due date (spec §21.1). A period covers every brand of the entity. Filter by `regimeId` (`EU_OSS_UNION` for the Union OSS return) or `status` to find the period to prepare, lock or package: those operations take its ID. Each period has its `periodKey` (`2026-Q3`, `2026-07` or `2026`), its first and last day in the entity's time zone, the `dueDate` and `dueAt` (23:59:59 local time), its `status` (`open`, `locked`, `prepared`, `submitted`, `paid`) and, once prepared, the report's `totals` in the filing currency. Paginate with `limit` (1–100, default 10) and `starting_after`. ## At a glance - **REST:** `GET /api/v1/filing_periods` - **MCP tool:** `filing_periods_list` - **Operation ID:** `filing_periods.list` - **Scope:** Legal entity - **Permission:** `filings:read` - **Risk tier:** `read` - **Dry run:** Not supported - **Idempotency:** Not needed (read only) - **Modes:** Test and live - **Pagination:** `limit` (at most 100) and `starting_after` - **Authentication:** API key with the `filings:read` scope - **Since:** M8 ## Request ### Query parameters | Field | Type | Required | Description | | ---------------- | ----------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------ | | `regimeId` | string | No | Only this regime's periods, e.g. `EU_OSS_UNION`. | | `status` | one of `open`, `locked`, `prepared`, `submitted`, `paid` or array of one of `open`, `locked`, `prepared`, `submitted`, `paid` | No | Only periods in this status (or these statuses). | | `limit` | integer (1 to 100) | No | Page size, 1 to 100 (default 10). | | `starting_after` | `fp_…` ID | No | The `next_cursor` of the previous page. | ## Response `200 OK` with a JSON object, a page of the list (newest first): | Field | Type | Description | | ------------------------ | -------------------------------------------------------------------------- | ------------------------------------------------------------ | | `object` | `"list"` | | | `data` | array of object | | | `data[].id` | `fp_…` ID | | | `data[].object` | `"filing_period"` | | | `data[].entityId` | `ent_…` ID | | | `data[].livemode` | boolean | | | `data[].regimeId` | string | | | `data[].registrationId` | `regn_…` ID | | | `data[].reportKind` | one of `eu_oss`, `eu_domestic`, `uk_vat`, `ch_mwst`, `generic`, `us_state` | | | `data[].reportAvailable` | boolean | | | `data[].frequency` | one of `monthly`, `quarterly`, `annual` | | | `data[].periodKey` | string | The period: "2026-Q3", "2026-07" or "2026". | | `data[].periodStart` | date-time | | | `data[].periodEnd` | date-time | The end (exclusive): the next period's first local midnight. | | `data[].firstDay` | string | | | `data[].lastDay` | string | | | `data[].timeZone` | string | | | `data[].currency` | string | | | `data[].dueDate` | string | | | `data[].dueAt` | date-time | 23:59:59 local time on the due date. | | `data[].lockableAt` | date-time | | | `data[].status` | one of `open`, `locked`, `prepared`, `submitted`, `paid` | | | `data[].statusChangedAt` | date-time | | | `data[].lockedAt` | date-time or null | | | `data[].preparedAt` | date-time or null | | | `data[].submittedAt` | date-time or null | | | `data[].reference` | string or null | | | `data[].paidAt` | date-time or null | | | `data[].paymentRef` | string or null | | | `data[].totals` | object or null | | | `data[].createdAt` | date-time | | | `data[].updatedAt` | date-time | | | `has_more` | boolean | | | `next_cursor` | `fp_…` ID or null | | ## Examples ### The OSS returns still to file ```http GET /api/v1/filing_periods?regimeId=EU_OSS_UNION&status=open&status=locked&status=prepared&limit=10 Authorization: Bearer or_test_… ``` Response (`200`): ```json { "object": "list", "data": [ { "id": "fp_01m4tx5nj8emwbyf7y9vcf47y1", "object": "filing_period", "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2", "livemode": true, "regimeId": "EU_OSS_UNION", "registrationId": "regn_01m4tx5nj8emwbyf7y9vcf47xk", "reportKind": "eu_oss", "reportAvailable": true, "frequency": "quarterly", "periodKey": "2026-Q4", "periodStart": "2026-09-30T22:00:00.000Z", "periodEnd": "2026-12-31T23:00:00.000Z", "firstDay": "2026-10-01", "lastDay": "2026-12-31", "timeZone": "Europe/Zagreb", "currency": "EUR", "dueDate": "2027-01-31", "dueAt": "2027-01-31T22:59:59.000Z", "lockableAt": "2026-12-31T23:00:00.000Z", "status": "open", "statusChangedAt": "2026-10-01T03:00:00.000Z", "lockedAt": null, "preparedAt": null, "submittedAt": null, "reference": null, "paidAt": null, "paymentRef": null, "totals": null, "createdAt": "2026-10-01T03:00:00.000Z", "updatedAt": "2026-10-01T03:00:00.000Z" }, { "id": "fp_01m4tx5nj8emwbyf7y9vcf47y0", "object": "filing_period", "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2", "livemode": true, "regimeId": "EU_OSS_UNION", "registrationId": "regn_01m4tx5nj8emwbyf7y9vcf47xk", "reportKind": "eu_oss", "reportAvailable": true, "frequency": "quarterly", "periodKey": "2026-Q3", "periodStart": "2026-06-30T22:00:00.000Z", "periodEnd": "2026-09-30T22:00:00.000Z", "firstDay": "2026-07-01", "lastDay": "2026-09-30", "timeZone": "Europe/Zagreb", "currency": "EUR", "dueDate": "2026-10-31", "dueAt": "2026-10-31T22:59:59.000Z", "lockableAt": "2026-09-30T22:00:00.000Z", "status": "prepared", "statusChangedAt": "2026-10-02T08:05:00.000Z", "lockedAt": "2026-10-02T08:00:00.000Z", "preparedAt": "2026-10-02T08:05:00.000Z", "submittedAt": null, "reference": null, "paidAt": null, "paymentRef": null, "totals": { "currency": "EUR", "taxable": "1500000000", "tax": "290000000", "corrections": "-19000000", "due": "271000000", "refundable": "0" }, "createdAt": "2026-07-01T03:00:00.000Z", "updatedAt": "2026-10-02T08:05:00.000Z" } ], "has_more": false, "next_cursor": null } ``` ## Errors | Code | HTTP status | When | What to do | | -------------------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed) | 400 | A filter or the page size is malformed (`details.issues`). | Fix the fields listed in `details.issues` and send the request again. | | [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required) | 400 | The request names no legal entity (an org key without `Ownrecord-Entity`). | Call the operation with credentials or a target at its level: an organization, a legal entity, a brand or the platform (`details.required_scope`). | | [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied) | 403 | You can't see this entity's filings (brand-scoped members never can). | Ask an organization owner or admin for a role or scope that allows this action. | It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found), [`dry_run_not_supported`](https://ownrecord.io/docs/reference/errors.md#dry_run_not_supported), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).