> ## Documentation Index > Fetch the complete documentation index at: https://docs.signupbreeze.com/llms.txt > Use this file to discover all available pages before exploring further. # Get an event's coverage > Answers "what still needs people?" in one call: how full every shift is, plus a summary of the event as a whole. Prefer this over listing shifts and signups separately. Working it out from those takes several requests and some arithmetic; this gives you the answer, which matters when the caller is an agent deciding what to do rather than a page rendering a table. `hours_until_start` is negative once the event has begun, so `slots_unfilled > 0` together with a small positive value is the "chase people now" signal. Requires the `events:read` scope. ## OpenAPI ````yaml https://api.signupbreeze.com/openapi.yaml get /v1/events/{event_id}/coverage openapi: 3.0.3 info: title: SignUpBreeze API description: >- Manage events, shifts, and signups programmatically — from your own scripts, an automation platform, or an AI agent. ## Authentication Every request needs a bearer token, which an organization owner or admin creates under **Organization settings → API**. Tokens belong to the organization rather than to the person who created one, so an admin leaving does not break a live integration. Each token carries a set of scopes, and every endpoint states the scope it requires. A request whose token lacks the scope is refused with `403`. **Every token expires**, after at most a year and by default after exactly that. An expired token is refused with `401`, the same as a revoked one, so plan to create a replacement before the expiry date shown in settings — nothing using the old token keeps working past it. ## Rate limiting Requests are throttled per API token, not per organization — issuing more tokens does not raise the ceiling. The limit varies by plan: 30 requests/min on Free and Calendar, 120 on Starter, 300 on Pro. Every response carries `X-RateLimit-Limit` and `X-RateLimit-Remaining`. Exceeding the limit returns `429`, with `Retry-After` and `X-RateLimit-Reset` added to that response so you know when to try again. ## Idempotency Writes accept an `Idempotency-Key` header. Send the same key again and the original response is replayed rather than the write happening twice — worth using anywhere a retry is possible, which is most places an agent is involved. ## Pagination Collections are cursor paginated. Follow `meta.next_cursor` rather than assuming page numbers. ## Scoping Everything a token can reach belongs to its organization. Another organization's record answers `404` rather than `403`, so a token cannot be used to discover that it exists. version: 1.0.0 servers: - url: https://api.signupbreeze.com security: - default: [] tags: - name: Events description: >- Create and manage events. Every endpoint is scoped to the organization that owns the token — another organization's event responds `404`, not `403`, so a token cannot be used to discover that it exists. - name: Organization description: |- The organization a token belongs to. - name: Shifts description: >- The time slots volunteers sign up for. Shift times are wall-clock strings like `14:30`, interpreted in the parent event's timezone against its start date — you never send a date or an offset for a shift. - name: Signups description: >- Who has signed up. Read-only in v1: signups are created through the public event page, which is deliberately the only way a volunteer is added. externalDocs: description: SignUpBreeze documentation url: https://docs.signupbreeze.com/api-reference/introduction paths: /v1/events/{event_id}/coverage: parameters: - in: path name: event_id description: The ID of the event. example: 019fdf11-4bb2-7039-92c3-9e7f1ee711a1 required: true schema: type: string - in: path name: event description: The event's id. example: 019fdf11-4bb2-7039-92c3-9e7f1ee711a1 required: true schema: type: string get: tags: - Events summary: Get an event's coverage description: >- Answers "what still needs people?" in one call: how full every shift is, plus a summary of the event as a whole. Prefer this over listing shifts and signups separately. Working it out from those takes several requests and some arithmetic; this gives you the answer, which matters when the caller is an agent deciding what to do rather than a page rendering a table. `hours_until_start` is negative once the event has begun, so `slots_unfilled > 0` together with a small positive value is the "chase people now" signal. Requires the `events:read` scope. operationId: getAnEventsCoverage parameters: [] responses: '200': description: '' content: application/json: schema: oneOf: - description: an event still needing volunteers type: object example: data: event: id: 019fdf11-4bb2-7039-92c3-9e7f1ee711a1 title: Fall Festival start_date: '2026-09-12T17:00:00+00:00' timezone: America/Los_Angeles is_published: true hours_until_start: 240 summary: slots_total: 2 slots_unfilled: 1 total_capacity: 7 total_filled: 6 total_remaining: 1 is_fully_staffed: false slots: - id: 019fdf11-4bc7-723f-96f0-fdf57ab20b07 title: Setup Crew start_time: '2026-09-12T16:00:00+00:00' end_time: '2026-09-12T18:00:00+00:00' capacity: 3 filled: 3 remaining: 0 is_full: true - id: 019fdf11-4bc8-7316-aea3-ab8f06439288 title: Clean-up Crew start_time: '2026-09-12T23:00:00+00:00' end_time: '2026-09-13T01:00:00+00:00' capacity: 4 filled: 3 remaining: 1 is_full: false properties: data: type: object properties: event: type: object properties: id: type: string example: 019fdf11-4bb2-7039-92c3-9e7f1ee711a1 title: type: string example: Fall Festival start_date: type: string example: '2026-09-12T17:00:00+00:00' timezone: type: string example: America/Los_Angeles is_published: type: boolean example: true hours_until_start: type: integer example: 240 description: >- Hours until the event starts. Negative once it has begun, null if it has no start date. summary: type: object properties: slots_total: type: integer example: 2 description: How many shifts the event has. slots_unfilled: type: integer example: 1 description: Shifts with at least one place still open. total_capacity: type: integer example: 7 description: Volunteers needed across every shift. total_filled: type: integer example: 6 description: Confirmed signups across every shift. total_remaining: type: integer example: 1 description: Places still open across every shift. is_fully_staffed: type: boolean example: false description: True when no shift has a place left. slots: type: array example: - id: 019fdf11-4bc7-723f-96f0-fdf57ab20b07 title: Setup Crew start_time: '2026-09-12T16:00:00+00:00' end_time: '2026-09-12T18:00:00+00:00' capacity: 3 filled: 3 remaining: 0 is_full: true - id: 019fdf11-4bc8-7316-aea3-ab8f06439288 title: Clean-up Crew start_time: '2026-09-12T23:00:00+00:00' end_time: '2026-09-13T01:00:00+00:00' capacity: 4 filled: 3 remaining: 1 is_full: false items: type: object properties: id: type: string example: 019fdf11-4bc7-723f-96f0-fdf57ab20b07 title: type: string example: Setup Crew start_time: type: string example: '2026-09-12T16:00:00+00:00' end_time: type: string example: '2026-09-12T18:00:00+00:00' capacity: type: integer example: 3 filled: type: integer example: 3 remaining: type: integer example: 0 is_full: type: boolean example: true - description: an event with nothing left to fill type: object example: data: event: id: 019fdf11-4bb2-7039-92c3-9e7f1ee711a1 title: Fall Festival start_date: '2026-09-12T17:00:00+00:00' timezone: America/Los_Angeles is_published: true hours_until_start: 240 summary: slots_total: 1 slots_unfilled: 0 total_capacity: 3 total_filled: 3 total_remaining: 0 is_fully_staffed: true slots: - id: 019fdf11-4bc7-723f-96f0-fdf57ab20b07 title: Setup Crew start_time: '2026-09-12T16:00:00+00:00' end_time: '2026-09-12T18:00:00+00:00' capacity: 3 filled: 3 remaining: 0 is_full: true properties: data: type: object properties: event: type: object properties: id: type: string example: 019fdf11-4bb2-7039-92c3-9e7f1ee711a1 title: type: string example: Fall Festival start_date: type: string example: '2026-09-12T17:00:00+00:00' timezone: type: string example: America/Los_Angeles is_published: type: boolean example: true hours_until_start: type: integer example: 240 description: >- Hours until the event starts. Negative once it has begun, null if it has no start date. summary: type: object properties: slots_total: type: integer example: 1 description: How many shifts the event has. slots_unfilled: type: integer example: 0 description: Shifts with at least one place still open. total_capacity: type: integer example: 3 description: Volunteers needed across every shift. total_filled: type: integer example: 3 description: Confirmed signups across every shift. total_remaining: type: integer example: 0 description: Places still open across every shift. is_fully_staffed: type: boolean example: true description: True when no shift has a place left. slots: type: array example: - id: 019fdf11-4bc7-723f-96f0-fdf57ab20b07 title: Setup Crew start_time: '2026-09-12T16:00:00+00:00' end_time: '2026-09-12T18:00:00+00:00' capacity: 3 filled: 3 remaining: 0 is_full: true items: type: object properties: id: type: string example: 019fdf11-4bc7-723f-96f0-fdf57ab20b07 title: type: string example: Setup Crew start_time: type: string example: '2026-09-12T16:00:00+00:00' end_time: type: string example: '2026-09-12T18:00:00+00:00' capacity: type: integer example: 3 filled: type: integer example: 3 remaining: type: integer example: 0 is_full: type: boolean example: true '404': description: no such event, or it belongs to another organization content: application/json: schema: type: object example: message: Not found. properties: message: type: string example: Not found. components: securitySchemes: default: type: http scheme: bearer description: >- Create a token under Organization settings → API. Tokens are shown once, on creation. They belong to the organization, not to you, so they keep working if you leave the team. API access is included on every plan; the rate limit depends on the plan. ````