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

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

# campaigns_settings

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

Returns the settings of one campaign: its label, industry, description, state, research, taxonomy presets, and daily opportunities email settings.

## What it does

The tool returns the settings of one campaign. It is the same data as the Settings tab of Edit Campaign in the web app: the label, the industry, the description, the state, whether the campaign is finalized, its research progress, its taxonomy presets, and its daily opportunities email settings. `campaign` is required.

This tool only reads. The change tools [`campaigns_update`](https://oppalerts.com/docs/api/campaigns_update), [`campaigns_set_taxonomy_presets`](https://oppalerts.com/docs/api/campaigns_set_taxonomy_presets), and [`campaigns_set_daily_opportunities_email`](https://oppalerts.com/docs/api/campaigns_set_daily_opportunities_email) change these settings, and each one returns data in this same format.

## Authentication

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

## Parameters

**`campaign`int, required, 1 to 4294967295**

The campaign id, from [campaigns_list](https://oppalerts.com/docs/mcp/campaigns_list). It must be a campaign of your account.

## Strict Rules

- A field that is not in the list above 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." The old name of a renamed field is refused in the same way.
- A bad value is refused, and the error names the field. A bad value is a value of the wrong type, a number with a fraction for a whole-number field, a value out of its range, or a value that is not in its list. A required field that you do not send is refused too. The tool never changes a value that you send.
- 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

**`campaign.id`int**

The campaign id.

**`campaign.label`string**

The name of the campaign.

**`campaign.industry`string**

The industry of the campaign.

**`campaign.description`string**

The description of the campaign. It is an empty string when the campaign has none.

**`campaign.state`string**

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

**`campaign.finalized`bool**

`true` when the campaign is finalized.

**`campaign.finalized_at`string**

The time when the campaign was finalized, as ISO 8601 text in UTC. Empty when `finalized` is `false`.

**`campaign.research`string**

The progress of the campaign’s research, with the values of `research` in [campaigns_list](https://oppalerts.com/docs/api/campaigns_list). The example shows `not_started`.

**`campaign.started_at`string**

The time when the campaign last counted as a start in the plan limit of campaigns started in 24 hours, as ISO 8601 text in UTC: its create, or [campaigns_activate](https://oppalerts.com/docs/api/campaigns_activate) of a campaign that was never finalized. Empty when the campaign has no such time.

**`campaign.taxonomy_presets`list**

The taxonomy presets of the campaign. Each item is one taxonomy category.

**`campaign.taxonomy_presets[].taxonomy`string**

The taxonomy of the category, as [taxonomy_taxonomies](https://oppalerts.com/docs/api/taxonomy_taxonomies) names it.

**`campaign.taxonomy_presets[].category_id`int**

The id of the category.

**`campaign.taxonomy_presets[].category_label`string**

The label of the category, for example `Travel > Travel Type > Hotels and Motels`.

**`campaign.daily_opportunities_email`object**

The daily opportunities email settings of the campaign.

**`campaign.daily_opportunities_email.enabled`bool**

`true` when the daily opportunities email is on.

**`campaign.daily_opportunities_email.email`string**

The address that gets the daily opportunities email.

**`campaign.daily_opportunities_email.first_name`string**

The first name used in the daily opportunities email.

**`campaign.daily_opportunities_email.send_hour`int**

The hour of the day when the daily opportunities email is sent, in `campaign.daily_opportunities_email.timezone`.

**`campaign.daily_opportunities_email.timezone`string**

The time zone of `send_hour`, for example `America/Los_Angeles`.

**`campaign.daily_opportunities_email.unsubscribed`bool**

`true` when the address unsubscribed from the daily opportunities email.

**`campaign.daily_opportunities_email.unsubscribed_at`string**

The time when the address unsubscribed with the link in the email, as ISO 8601 text in UTC. Empty when `unsubscribed` is `false`.

**`missing_before_finalize`list of strings**

What [campaigns_finalize](https://oppalerts.com/docs/api/campaigns_finalize) needs before it can run, one sentence for each item, in the words of its `not_ready` refusal. Empty when nothing is missing. A finalized campaign has the list too. Only this tool returns this list: the change tools return only the campaign object.

**`daily_opportunities_emails_sent`list**

The campaign’s 30 most recent daily opportunities emails, newest first. Each has `date` (the day that the email reports, YYYY-MM-DD), `sent` (`true` when the mail server took the email, `false` when it refused it), `sent_to` (the address), `sent_at` (the time of the send, as ISO 8601 text in UTC), and `opportunities_found` (the pages that the saved opportunities found that day on both indexes). Only this tool returns this list.

## Example

### Request

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

### Response

The response is shown in full.

```json
{
  "campaign": {
    "id": 124,
    "label": "Boutique Hotels",
    "industry": "Boutique hotels",
    "description": "Boutique hotel brands competing for direct bookings in mid-size US cities, against the online travel agencies and the big hotel chains.",
    "state": "active",
    "finalized": false,
    "finalized_at": "",
    "research": "not_started",
    "started_at": "2026-11-01T15:04:05Z",
    "taxonomy_presets": [
      {
        "taxonomy": "iab-content-taxonomy",
        "category_id": 2358064203319202,
        "category_label": "Travel > Travel Type > Hotels and Motels"
      }
    ],
    "daily_opportunities_email": {
      "enabled": true,
      "email": "pat@example.com",
      "first_name": "Pat",
      "send_hour": 7,
      "timezone": "America/Los_Angeles",
      "unsubscribed": false,
      "unsubscribed_at": ""
    }
  },
  "missing_before_finalize": [
    "The campaign needs one owned brand with a host name."
  ],
  "daily_opportunities_emails_sent": [
    {
      "date": "2026-09-01",
      "sent": true,
      "sent_to": "pat@example.com",
      "sent_at": "2026-09-01T14:00:07Z",
      "opportunities_found": 26
    },
    {
      "date": "2026-08-31",
      "sent": false,
      "sent_to": "pat@example.com",
      "sent_at": "2026-08-31T14:00:05Z",
      "opportunities_found": 15
    }
  ]
}
```

## Errors

- `bad_param` (HTTP 400): a field is not a field of this tool, a required field is not sent, or a value has the wrong type or is out of its range. The error names the field.
- `no_campaign` (HTTP 404): the campaign is not in this account
- `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_settings`. See [campaigns_settings in MCP](https://oppalerts.com/docs/mcp/campaigns_settings).

## Related pages

- [Edit Campaign in the web app: the Settings tab](https://oppalerts.com/docs/app/campaign/edit)
- [campaigns_settings in MCP](https://oppalerts.com/docs/mcp/campaigns_settings)
- [campaigns_list](https://oppalerts.com/docs/api/campaigns_list): the campaigns of the account and their ids
- [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
- [Use case: Research a New Client Market](https://oppalerts.com/docs/how-to/research-a-new-client-market)
