Documentation / MCP / campaigns_list

campaigns_list

POSThttps://mcp.oppalerts.com/mcptool: 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, campaigns_organizations, and campaigns_saved_opportunities.

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

Connect

claude mcp add --transport http oppalerts https://mcp.oppalerts.com/mcp

The first call opens a browser window for the OppAlerts login. Connect an AI Agent has the details.

Parameters

This tool has no parameters. Send an empty object.

Strict Rules

  • This tool accepts no fields. Any field you send is refused. The result then has isError true, and its text starts with 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_countint
The number of active campaigns across the account. The campaigns that a team member cannot open are included.
plan_active_campaign_limitint
The number of active campaigns the account’s plan allows.
campaignslist
One item for each campaign. The items are ordered by state, then label.
campaigns[].idint
The campaign id. Pass it as campaign to the other campaign tools.
campaigns[].labelstring
The name of the campaign.
campaigns[].industrystring
The industry of the campaign.
campaigns[].statestring
The state of the campaign. The example shows active.
campaigns[].finalizedbool
true when the campaign is finalized.
campaigns[].researchstring
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_atstring
The time when the research finished, as ISO 8601 text in UTC. Empty when research is not finished.
campaigns[].organization_countint
The number of organizations of the campaign, as campaigns_organizations lists them.
campaigns[].created_atstring
The time when the campaign was created, as ISO 8601 text in UTC.

Example

Call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "campaigns_list",
    "arguments": {}
  }
}

Response

The response is shown in full.

{
  "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

An error returns as a tool result with isError true. Its text starts with the error code, except for daily_limit, whose text is only the sentence. The HTTP status shown for each code is its API status.

  • bad_param (HTTP 400 in the API): the request has a field. This tool accepts no fields, and the error names the field you sent.
  • db_error (HTTP 500 in the API): the data could not be read
  • daily_limit (HTTP 429 in the API): the account has used all its calls for this tool today. 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 data in the API

POST /v1/campaigns/list HTTP/1.1
Host: api.oppalerts.com
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{}