<!-- The markdown copy of https://oppalerts.com/docs/api/campaigns_list . All pages: https://oppalerts.com/docs/llms.txt -->

[Documentation](https://oppalerts.com/docs/) / [API](https://oppalerts.com/docs/api/) / campaigns_list

# campaigns_list

`POST https://api.oppalerts.com/v1/campaigns/list`

Lists every campaign in your account, with its id, label, state, whether it is finalized, and its research progress.

## What it does

The tool returns one summary row for each campaign in the account. It does not search an index. The ids in the answer are the values that every other campaign tool takes in its `campaign` parameter.

For details of one campaign, use [campaigns_settings](https://oppalerts.com/docs/mcp/campaigns_settings), [campaigns_organizations](https://oppalerts.com/docs/mcp/campaigns_organizations), and [campaigns_saved_opportunities](https://oppalerts.com/docs/mcp/campaigns_saved_opportunities).

A team member who can open only some campaigns sees only those campaigns in the answer.

## Authentication

Send your token in the `Authorization: Bearer` header. [The API overview](https://oppalerts.com/docs/api/) explains how to get a token.

## Parameters

This tool has no parameters. Send an empty object.

## Strict Rules

- This tool accepts no fields. Any field you send is refused. The answer is HTTP 400 with the error code `bad_param`. The error names the field: "<field> is not a field of this tool."
- An error about the format of a call, such as a refused field, names the field. Its message ends with one sentence: "Read the documentation at https://oppalerts.com/docs for the correct format." Every other error has only its own sentence.

## Response fields

**`account_active_campaign_count`int**

The number of active campaigns across the account. The campaigns that a team member cannot open are included.

**`plan_active_campaign_limit`int**

The number of active campaigns the account’s plan allows.

**`campaigns`list**

One item for each campaign. The items are ordered by state, then label.

**`campaigns[].id`int**

The campaign id. Pass it as `campaign` to the other campaign tools.

**`campaigns[].label`string**

The name of the campaign.

**`campaigns[].industry`string**

The industry of the campaign.

**`campaigns[].state`string**

The state of the campaign. The example shows `active`.

**`campaigns[].finalized`bool**

`true` when the campaign is finalized.

**`campaigns[].research`string**

The progress of the campaign’s one-time research. The values are `not_started`, `waiting_to_start`, `queued`, `running`, `finished`, and `stopped`.

**`campaigns[].research_finished_at`string**

The time when the research finished, as ISO 8601 text in UTC. Empty when `research` is not `finished`.

**`campaigns[].organization_count`int**

The number of organizations of the campaign, as [campaigns_organizations](https://oppalerts.com/docs/api/campaigns_organizations) lists them.

**`campaigns[].created_at`string**

The time when the campaign was created, as ISO 8601 text in UTC.

## Example

### Request

```bash
curl -X POST https://api.oppalerts.com/v1/campaigns/list \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Response

The response is shown in full.

```json
{
  "account_active_campaign_count": 2,
  "plan_active_campaign_limit": 5,
  "campaigns": [
    {
      "id": 3,
      "label": "Hotels",
      "industry": "Hotels",
      "state": "active",
      "finalized": true,
      "research": "finished",
      "research_finished_at": "2026-09-02T14:20:11Z",
      "organization_count": 6,
      "created_at": "2026-08-31T18:02:45Z"
    },
    {
      "id": 4,
      "label": "Fitness Clubs",
      "industry": "Fitness clubs",
      "state": "active",
      "finalized": false,
      "research": "not_started",
      "research_finished_at": "",
      "organization_count": 0,
      "created_at": "2026-11-01T15:04:05Z"
    }
  ]
}
```

## Errors

- `bad_param` (HTTP 400): the request has a field. This tool accepts no fields, and the error names the field you sent.
- `db_error` (HTTP 500): the data could not be read
- `daily_limit` (HTTP 429): the account has used all its calls for this tool today. [account_calls_left](https://oppalerts.com/docs/api/account_calls_left) shows when the count resets.

This tool has its own daily count. A call through the API or MCP uses one call from this count. A web app page reading the same data does not count. It is not an index search, so it does not use the shared count of the `news_` and `prospects_` tools, and the error `one_at_a_time` does not apply to it.

## Same tool in MCP

The MCP tool is `campaigns_list`. See [campaigns_list in MCP](https://oppalerts.com/docs/mcp/campaigns_list).

## Related pages

- [List Campaigns in the web app](https://oppalerts.com/docs/app/)
- [Edit Campaign in the web app](https://oppalerts.com/docs/app/campaign/edit)
- [campaigns_list in MCP](https://oppalerts.com/docs/mcp/campaigns_list)
- [campaigns_settings](https://oppalerts.com/docs/api/campaigns_settings): the settings of one campaign
- [campaigns_organizations](https://oppalerts.com/docs/api/campaigns_organizations): the organizations of one campaign
- [campaigns_saved_opportunities](https://oppalerts.com/docs/api/campaigns_saved_opportunities): the saved opportunities of one campaign
- [campaigns_dashboard](https://oppalerts.com/docs/api/campaigns_dashboard): the dashboard read of one campaign
- [Use case: Review Client Campaign Progress](https://oppalerts.com/docs/how-to/review-client-campaign-progress)
