---
title: "Start a report job (async: 202 Accepted, then poll)"
method: POST
path: "/api/v1/reports"
tags: ["reports"]
---

# Start a report job (async: 202 Accepted, then poll)

`POST /api/v1/reports`

## Request

- Base URL: `https://jointhestudentlife.com`
- URL: `https://jointhestudentlife.com/api/v1/reports`
- Auth: none required

Report jobs follow the async job pattern: this answers 202 Accepted with a job id and a Location header; poll GET /api/v1/reports/{id} until status is succeeded. No side effects and nothing is stored. An unknown city in the body is a 400.

## Request body

- ReportRequest
  - `type` 'city_comparison' | 'events_overview', required: city_comparison: monthly costs, everyday prices and upcoming events with the cheapest ticket, side by side (2 to 10 cities). events_overview: every upcoming event with ticket status and the cheapest ticket, counted by type and status.
  - `cities` string[]: City slugs or names. Required (2 to 10) for city_comparison; optional filter for events_overview.
  - `event_type` 'all' | 'halloween' | 'welcome_festival' | 'semester_kickoff' | 'orientation_week': events_overview only.

## Response `202`

Accepted. Poll the Location.

- ReportJob
  - `id` string, required: Job id. Opaque: pass it back unchanged.
  - `type` 'city_comparison' | 'events_overview', required
  - `status` 'pending' | 'succeeded', required: pending right after POST; succeeded when polled. The report is built from the data at the moment you poll.
  - `created_at` string, date-time
  - `expires_at` string, date-time: 24 hours after creation. Polling after that gets 410.
  - `completed_at` string, date-time
  - `status_url` string, uri, required: Where to poll. Same as the Location header.
  - `poll_after_seconds` integer
  - `data_updated` string
  - `result` object: Present when status is succeeded. city_comparison: {cities: [...]}. events_overview: {total, by_type, by_ticket_status, events: [...]}.
  - `note` string

## Other responses

- `400`: Error
- `413`: Error
- `429`: Rate limited
- `default`: Error

---

[API](https://skmtc.dev/jointhestudentlife/apis/the-student-life-api.md) · [All operations](https://skmtc.dev/jointhestudentlife/apis/the-student-life-api/llms.txt) · [OpenAPI document](https://skmtc.dev/jointhestudentlife/apis/the-student-life-api/revisions/d04925a4902b?raw)