# List filing schedules > The filing_periods.schedules operation: GET /api/v1/filing_schedules in the REST API and the filing_periods_schedules tool in the MCP server. The filing schedule of each of the entity's registrations that files returns (registered, in a grace period or deregistered), or that has periods or a schedule of its own, in the mode of the request (spec §21.1). A schedule is the regime's filing spec (frequency and due rule, from the knowledge base) unless an operator set one on the registration with `filing_periods.set_schedule` (the frequency and stagger the tax authority assigned, and a due rule where the spec's can't be computed). `problem` says why no periods can be generated (`due_other`, `frequency_varies`: set a schedule; `no_filing_spec`: the knowledge base has no filing rules for the regime yet). `nextPeriodStart` and `nextDueAt` are the earliest period still to file. ## At a glance - **REST:** `GET /api/v1/filing_schedules` - **MCP tool:** `filing_periods_schedules` - **Operation ID:** `filing_periods.schedules` - **Scope:** Legal entity - **Permission:** `filings:read` - **Risk tier:** `read` - **Dry run:** Not supported - **Idempotency:** Not needed (read only) - **Modes:** Test and live - **Authentication:** API key with the `filings:read` scope - **Since:** M8 ## Request ### Query parameters | Field | Type | Required | Description | | ---------- | ------ | -------- | ----------------- | | `regimeId` | string | No | Only this regime. | ## Response `200 OK` with a JSON object: | Field | Type | Description | | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | `object` | `"list"` | | | `data` | array of object | | | `data[].object` | `"filing_schedule"` | | | `data[].regimeId` | string | | | `data[].registrationId` | `regn_…` ID | | | `data[].registrationState` | one of `not_applicable`, `monitored`, `pre_registration`, `grace`, `registered`, `blocked_b2c`, `deregistered` | | | `data[].reportKind` | one of `eu_oss`, `eu_domestic`, `uk_vat`, `ch_mwst`, `generic`, `us_state` or null | | | `data[].filingSpecId` | string or null | | | `data[].currency` | string or null | | | `data[].frequency` | one of `monthly`, `quarterly`, `annual` or null | | | `data[].startMonth` | integer or null | | | `data[].due` | object or null | | | `data[].source` | object or null | | | `data[].problem` | one of `no_filing_spec`, `frequency_varies`, `due_other`, `due_days_missing`, `due_nth_day_missing`, `due_months_missing`, `regime_missing` or null | | | `data[].filingSpec` | object or null | | | `data[].registrationSchedule` | object or null | | | `data[].nextPeriodStart` | date-time or null | | | `data[].nextDueAt` | date-time or null | | | `data[].periods` | integer | | ## Examples ### The entity's filing schedules ```http GET /api/v1/filing_schedules Authorization: Bearer or_test_… ``` Response (`200`): ```json { "object": "list", "data": [ { "object": "filing_schedule", "regimeId": "EU_OSS_UNION", "registrationId": "regn_01m4tx5nj8emwbyf7y9vcf47xk", "registrationState": "registered", "reportKind": "eu_oss", "filingSpecId": "kn_01m4tx5nj8emwbyf7y9vcf47y8", "currency": "EUR", "frequency": "quarterly", "startMonth": 1, "due": { "kind": "end_of_following_month", "days": null, "nthDay": null, "months": null, "description": "the last day of the month after the period" }, "source": { "frequency": "filing_spec", "due": "filing_spec" }, "problem": null, "filingSpec": { "frequency": "quarterly", "due": { "kind": "end_of_following_month", "days": null, "nthDay": null, "months": null, "description": "the last day of the month after the period" } }, "registrationSchedule": null, "nextPeriodStart": "2026-06-30T22:00:00.000Z", "nextDueAt": "2026-10-31T22:59:59.000Z", "periods": 3 }, { "object": "filing_schedule", "regimeId": "GB_VAT_NETP", "registrationId": "regn_01m4tx5nj8emwbyf7y9vcf47y6", "registrationState": "registered", "reportKind": "uk_vat", "filingSpecId": "kn_01m4tx5nj8emwbyf7y9vcf47y7", "currency": "GBP", "frequency": "quarterly", "startMonth": 2, "due": { "kind": "months_and_days_after_period_end", "days": 7, "nthDay": null, "months": 1, "description": "1 month and 7 days after the period ends" }, "source": { "frequency": "registration", "due": "registration" }, "problem": null, "filingSpec": { "frequency": "quarterly", "due": { "kind": "other", "days": null, "nthDay": null, "months": null, "description": "a rule Ownrecord can't compute: set a due rule on the registration" } }, "registrationSchedule": { "frequency": "quarterly", "startMonth": 2, "due": { "kind": "months_and_days_after_period_end", "days": 7, "nthDay": null, "months": 1, "description": "1 month and 7 days after the period ends" }, "note": "Stagger 2 per the VAT registration certificate", "setAt": "2026-10-20T09:00:00.000Z", "setBy": "usr_01m4tx5nj8emwbyf7y9vcf47xa" }, "nextPeriodStart": "2026-07-31T23:00:00.000Z", "nextDueAt": "2026-12-07T23:59:59.000Z", "periods": 2 } ] } ``` ## Errors | Code | HTTP status | When | What to do | | -------------------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed) | 400 | `regimeId` is malformed. | 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. | 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).