# Organization API: Org Staff Bulk Runs

> Every Organization API operation tagged Org Staff Bulk Runs.

Source: https://www.coritan.com/docs/api/reference/organizations/org-staff-bulk-runs/

Base URL: `https://api.coritan.com/api/v1`. Paths below are complete.

To try these requests in the browser, open the [interactive Organization API reference](https://api.coritan.com/docs/org).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/staff/abuse/bulk-runs`](#op-get-api-v1-orgs-org-slug-staff-abuse-bulk-runs) | The brand's bulk runs, newest first, as {"runs": [...], "total": N} |
| POST | [`/api/v1/orgs/{org_slug}/staff/abuse/bulk-runs`](#op-post-api-v1-orgs-org-slug-staff-abuse-bulk-runs) | Start one action over every account or server a filter matches |
| POST | [`/api/v1/orgs/{org_slug}/staff/abuse/bulk-runs/preview`](#op-post-api-v1-orgs-org-slug-staff-abuse-bulk-runs-preview) | How many accounts or servers a run with this filter would act on |
| GET | [`/api/v1/orgs/{org_slug}/staff/abuse/bulk-runs/{uuid}`](#op-get-api-v1-orgs-org-slug-staff-abuse-bulk-runs-uuid) | One bulk run and its progress |
| POST | [`/api/v1/orgs/{org_slug}/staff/abuse/bulk-runs/{uuid}/cancel`](#op-post-api-v1-orgs-org-slug-staff-abuse-bulk-runs-uuid-cancel) | Stop a run that has not finished |

### The brand's bulk runs, newest first, as {"runs": [...], "total": N} {#op-get-api-v1-orgs-org-slug-staff-abuse-bulk-runs}

`GET /api/v1/orgs/{org_slug}/staff/abuse/bulk-runs`

The brand's bulk runs, newest first, as ``{"runs": [...], "total": N}``.

Each run says what it does (``target``, ``action``, ``filter``,
``reason``), where it is (``status``: queued, running, done, failed or
cancelled) and how far it got (``total``, ``processed``, ``applied``,
``skipped``). ``pattern`` names the pattern a ``pattern_id`` filter
acted on (``id``, ``kind``, ``value``), and is null for any other
filter. Tier 3 support and up.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `limit` | query | integer | no | At most this many runs. Default: `50`. |
| `offset` | query | integer | no | Skip this many runs, for paging. Default: `0`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Start one action over every account or server a filter matches {#op-post-api-v1-orgs-org-slug-staff-abuse-bulk-runs}

`POST /api/v1/orgs/{org_slug}/staff/abuse/bulk-runs`

Start one action over every account or server a filter matches.

Send the filter the directory (``GET /staff/customers``) or the fleet
(``GET /staff/servers``) was showing and the total it showed as
``expected_total``. The run resolves the selection once, with the same
query that list uses, and answers the run with 201; it then works
through the selection in the background, 100 at a time, and ``GET
/staff/abuse/bulk-runs/{uuid}`` shows its progress.

Refused with 409 ``selection_changed`` (and the current ``total``) when
the filter no longer matches ``expected_total`` rows, and with 422 when
the filter narrows nothing or is not one the list takes, when nothing
matches, or when more rows match than a run takes
(``abuse.bulk_run_max``, 20000).
Support may suspend and unsuspend; terminate, ban, pause and a deletion
date need an org admin who stepped up in the last ten minutes. Each
staff member may start 6 runs an hour. A run opens tickets and emails
customers only when ``open_ticket`` and ``notify_customer`` say so.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `target` | string | yes | customers (the directory) or servers (the fleet). |
| `filter` | Filter | no | The list's own parameters. customers: q, status_filter, tag, audience, email_domain, created_after, created_before, discord, pattern_id. servers: q, status, audience, node_id, customer_id, name, owner, software, created_after, created_before, pattern_id. At least one that narrows: all as audience, status or status_filter, and a q of only *, count as blank. |
| `expected_total` | integer | yes | The total the list showed for this filter. A different count answers 409. |
| `action` | string | yes | suspend, unsuspend, terminate, ban or pause. |
| `reason` | string | yes | Why, for the audit log and any ticket. |
| `delete_after_days` | integer or null | no | suspend only: delete what is suspended this many days from now. |
| `open_ticket` | boolean | no | Open one ticket per customer, with the reason kept internal. |
| `notify_customer` | boolean | no | terminate only: send the cancellation email. |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### How many accounts or servers a run with this filter would act on {#op-post-api-v1-orgs-org-slug-staff-abuse-bulk-runs-preview}

`POST /api/v1/orgs/{org_slug}/staff/abuse/bulk-runs/preview`

How many accounts or servers a run with this filter would act on.

Answers ``{"target", "filter", "total", "max"}``: send ``total`` back as
a run's ``expected_total``. The fleet list pages without a total, so this
is where a server run's count comes from. Changes nothing, and refuses
an empty or unknown filter with 422 as a run does. Tier 3 support and up.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `target` | string | yes | customers (the directory) or servers (the fleet). |
| `filter` | Filter | no | The list's own parameters, as for a run. At least one. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### One bulk run and its progress {#op-get-api-v1-orgs-org-slug-staff-abuse-bulk-runs-uuid}

`GET /api/v1/orgs/{org_slug}/staff/abuse/bulk-runs/{uuid}`

One bulk run and its progress. ``last_error`` says why a failed run
stopped. Another brand's run answers 404.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Stop a run that has not finished {#op-post-api-v1-orgs-org-slug-staff-abuse-bulk-runs-uuid-cancel}

`POST /api/v1/orgs/{org_slug}/staff/abuse/bulk-runs/{uuid}/cancel`

Stop a run that has not finished. It reads ``cancelled`` at once and
stops before its next chunk of 100; what it already did stays done.
A run that already finished answers 409. Tier 3 support and up.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |