> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tumban.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List org scans

> List recent scans across the organization.

List recent scans for the organization, sorted newest first. Useful for
populating dashboards and review queues.

```http theme={null}
GET /api/v2/org/scans
```

<Note>
  Visibility is org-wide by design — every member of the organization
  sees every scan, not just the ones they submitted themselves.
</Note>

## Query parameters

<ParamField query="limit" type="integer" default="20">
  Maximum number of scans to return. Range: `1`–`100`.
</ParamField>

<ParamField query="after" type="string">
  Pagination cursor. Pass the `next_cursor` from the previous response
  to fetch the next page; omit it for the first page.
</ParamField>

<ParamField query="recommendation" type="string">
  Comma-separated list of recommendation values to restrict results to,
  for example `review_high,review_medium`. Allowed values: `no_flags`,
  `review_low`, `review_medium`, `review_high`. When this parameter is
  set, only completed scans are returned.
</ParamField>

<ParamField query="scan_mode" type="string">
  Restrict to a single scan mode: `quick` or `deep`. `deep` also
  matches legacy scans recorded before scan modes existed.
</ParamField>

<ParamField query="q" type="string">
  Case-insensitive substring search over the profile URL and username,
  for example `buymeacoffee.com/john` or `john`.
</ParamField>

<ParamField query="from_date" type="string">
  Earliest submission date to include, `YYYY-MM-DD` (UTC, inclusive). A
  malformed value returns `400`.
</ParamField>

<ParamField query="to_date" type="string">
  Latest submission date to include, `YYYY-MM-DD` (UTC, inclusive). A
  malformed value returns `400`.
</ParamField>

<ParamField query="sort_by" type="string" default="created_at">
  Field to sort by: `created_at` or `risk_score`.
</ParamField>

<ParamField query="sort_order" type="string" default="desc">
  Sort direction: `desc` (default) or `asc`.
</ParamField>

## Response

<ResponseField name="scans" type="object[]" required>
  List of scan summaries.
</ResponseField>

<ResponseField name="next_cursor" type="string">
  Opaque cursor for the next page. Pass it back as the `after` query
  parameter. `null` when there are no further results.
</ResponseField>

<ResponseField name="has_more" type="boolean" required>
  `true` when more scans match beyond this page (`next_cursor` is set).
</ResponseField>

<ResponseField name="fetched_at" type="string" required>
  ISO 8601 UTC timestamp of when the response was generated.
</ResponseField>

### `scans[]`

<ResponseField name="scan_id" type="string" required>
  Use with [`GET /api/v2/scans/{scan_id}`](/api/scans/get) to fetch the
  full record.
</ResponseField>

<ResponseField name="profile_url" type="string" required>
  The submitted profile URL.
</ResponseField>

<ResponseField name="status" type="string" required>
  See [Status values](/reference/status). Includes `processing` so
  in-flight scans are visible.
</ResponseField>

<ResponseField name="scan_mode" type="string">
  `quick` or `deep`. `null` on legacy scans recorded before scan modes
  existed.
</ResponseField>

<ResponseField name="submitted_at" type="string" required>
  ISO 8601 UTC timestamp.
</ResponseField>

<ResponseField name="completed_at" type="string">
  ISO 8601 UTC timestamp; `null` if the scan is still processing.
</ResponseField>

<ResponseField name="recommendation" type="string">
  See [Recommendation values](/reference/recommendation). `null` for
  scans that have not produced a triage report.
</ResponseField>

<ResponseField name="risk_score" type="integer">
  0–100. `null` for scans without a triage report.
</ResponseField>

<ResponseField name="confidence" type="string">
  `low`, `medium`, or `high`. `null` for scans without a triage report.
</ResponseField>

## Example

```bash theme={null}
curl "https://api-v2.tumban.com/api/v2/org/scans?limit=5&recommendation=review_high,review_medium" \
  -H "Authorization: Bearer sk_xxx"
```

```json theme={null}
{
  "scans": [
    {
      "scan_id": "550e8400-e29b-41d4-a716-446655440000",
      "profile_url": "https://creator.example/username",
      "status": "completed",
      "scan_mode": "deep",
      "submitted_at": "2026-04-29T12:00:00.123456+00:00",
      "completed_at": "2026-04-29T12:01:38.987654+00:00",
      "recommendation": "review_high",
      "risk_score": 85,
      "confidence": "high"
    }
  ],
  "next_cursor": "eyJmIjoiY3JlYXRlZF9hdCIsInYiOiIyMDI2LTA0LTI5VDEyOjAwOjAwKzAwOjAwIn0",
  "has_more": true,
  "fetched_at": "2026-04-29T12:34:56.654321+00:00"
}
```

## Errors

| Status | Detail                                                                                                                                   |
| ------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| 400    | `Invalid recommendation values: [...]` — one or more values in `recommendation` are not allowed.                                         |
| 400    | `from_date must be YYYY-MM-DD` / `to_date must be YYYY-MM-DD` — the date filter is malformed.                                            |
| 400    | `from_date is not a valid calendar date` / `to_date is not a valid calendar date` — well-formed but not a real date (e.g. `2026-02-30`). |

## Using the dashboard

Both the **Home** and **History** pages read from this endpoint:

* **Home → Action Items** tile — count of last-30-day scans with
  `recommendation` of `review_high` or `review_medium`; clicking it
  deep-links into **History** with that filter applied.
* **Home → Recent scans** — the most recent scans of any status.
* **History** — the full search/filter view (recommendation, scan mode,
  date range, and URL/username search), with pagination.

The Home page polls in-flight (`processing`) scans every five seconds
and updates rows in place. Click any non-processing row to open
[Get scan](/api/scans/get) detail.