---
title: "List reported mail"
method: GET
path: "/reports"
tags: ["reports"]
---

# List reported mail

`GET /reports`

## Request

- Base URL: `https://api.fallax.io/v1`
- URL: `https://api.fallax.io/v1/reports`
- Auth: HTTP bearer

Every message forwarded to the report mailbox, read back from Gmail's Alert Center, or filed with the Fallax button in Gmail. `verdict` is `simulation` when the message was matched to something Fallax sent, and `unknown` when it matched nothing, which is the pile of real suspicious mail worth triaging.

## Query parameters

- `limit` string: Rows per page, 1 to 200. Defaults to 50. A page comes back with a `nextCursor` when there are more.
- `cursor` string: The `nextCursor` from the previous page. Paging is by cursor rather than by offset, so rows written while you page are never skipped.
- `since` string: Only rows after this instant, exclusive. ISO 8601 or epoch milliseconds. This is the parameter a poll trigger uses: pass the timestamp of the newest row you have already handled.
- `order` 'desc' | 'asc': `desc` (the default) for newest first, which is what a person reading a page wants. `asc` for oldest first, which is what anything resuming from a watermark wants: with `since` and a limit, an ascending page is the oldest rows you have not seen, so a backlog drains in order instead of the newest page hiding the rest.
- `verdict` 'simulation' | 'unknown': `simulation` or `unknown`. Omit for both.
- `credited` 'true' | 'false': `true` to return only the report that credited a person for reporting, rather than every copy of it.

## Response `200`

List reported mail

- ReportPage
  - `data` Report[], required
    - `id` string, required
    - `reportedAt` string, date-time, nullable, required
    - `receivedAt` string, date-time, nullable, required
    - `source` string, required
    - `reporterEmail` string, nullable, required
    - `subject` string, nullable, required
    - `verdict` string, required
    - `credited` boolean, required
    - `dismissed` boolean, required
    - `webLink` string, nullable, required
    - `campaign` object, nullable, required
      - `id` string, required
      - `name` string, nullable, required
  - `nextCursor` string, nullable, required: Pass as `cursor` for the next page.
  - `hasMore` boolean, required

## Other responses

- `400`: A parameter or body field the API cannot use. The message names the field.
- `401`: No key, an unknown key, or one that has been revoked.
- `403`: A read-only key was used on a write endpoint.
- `404`: No such endpoint, or no such row in this workspace. The two are deliberately indistinguishable from outside: another workspace's ids must not be probeable.
- `405`: The path exists but not with that verb. `Allow` lists the verbs that work.
- `429`: More than 120 requests in a minute on one key. `Retry-After` says how long to wait. A poll every minute, and the paging behind it, is nowhere near this.
- `500`: Our fault. Safe to retry.

---

[API](https://skmtc.dev/fallax/apis/fallax-api.md) · [All operations](https://skmtc.dev/fallax/apis/fallax-api/llms.txt) · [OpenAPI document](https://skmtc.dev/fallax/apis/fallax-api/revisions/b5731fd85ef8?raw)