<!-- The markdown copy of https://oppalerts.com/docs/getting-started/your-first-api-call . All pages: https://oppalerts.com/docs/llms.txt -->

[Documentation](https://oppalerts.com/docs/) / [Getting Started](https://oppalerts.com/docs/getting-started/) / Your First API Call

# Your First API Call

Check your daily usage, list your campaigns, and search the News Index, with a sample response for each call.

## Before you start

- Get a token: [Create an API Token](https://oppalerts.com/docs/getting-started/create-an-api-token).
- Send every call as a `POST` with a JSON body to `https://api.oppalerts.com/v1/`.
- Send the token in the header `Authorization: Bearer YOUR_TOKEN`.

## 1. Check your daily counts

This call does not use an index search. It shows how many calls your account has left today.

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

The sample response below includes the `unlimited` field, which appears only for an administrator.

```json
{
  "resets_at": "2026-11-07T09:00:00Z",
  "index_searches": {
    "used": 3,
    "limit": 10,
    "left": 7,
    "tools": [
      "news_search",
      "prospects_search",
      "news_brand_mentions"
    ]
  },
  "tools": {
    "account_calls_left": {
      "used": 2,
      "limit": 100,
      "left": 98
    },
    "backlinks": {
      "used": 0,
      "limit": 10,
      "left": 10
    },
    "campaigns_dashboard": {
      "used": 4,
      "limit": 100,
      "left": 96
    }
  },
  "unlimited": true
}
```

## 2. List your campaigns

Most tools need a campaign ID. This call returns the ID of each campaign.

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

```json
{
  "campaigns": [
    {
      "id": 3,
      "label": "Hotels",
      "state": "active",
      "finalized": true,
      "research": "finished"
    },
    {
      "id": 4,
      "label": "Fitness Clubs",
      "state": "active",
      "finalized": false,
      "research": "not_started"
    }
  ]
}
```

- `finalized` is `true` when the campaign's research has started.
- `research` shows the research progress.

## 3. Search the News Index by semantic similarity

This call is an index search. It finds news pages in your campaign's market that are semantically similar to `similarity_text`.

```bash
curl -X POST https://api.oppalerts.com/v1/news/search \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"campaign": 3, "similarity_target": "similarity_text", "similarity_text": "Boutique hotels winning direct bookings from younger travelers in mid-size US cities.", "published_from": "2026-08-01", "pr_domain_min": 20, "type_scores": [{"opportunity_type": "advertising/newsletter-ads", "type_score_min": 50}], "sort": "best", "results_limit": 100}'
```

The full sample response:

```json
{
  "total_matches": 1240,
  "returned": 100,
  "results": [
    {
      "id": "1152921504611003120",
      "url": "https://cityguide-example.org/advertise/media-kit",
      "host": "cityguide-example.org",
      "document_type": "page",
      "published_at": "2026-05-10T00:00:00Z",
      "indexed_at": "2026-08-17T21:00:00Z",
      "pr_host": 39,
      "prot_host": 678,
      "pr_domain": 61,
      "prot_domain": 861,
      "similarity_score": 46.8,
      "relevance_weight": 1247.0,
      "org": {
        "relationship": "org_publisher"
      },
      "page": {
        "title": "Advertise with City Guide: media kit",
        "snippet": "Reach 400,000 monthly readers planning weekend trips. Sponsorship and hotel placements available.",
        "link_counts": {
          "article": {
            "follow": 12,
            "nofollow": 3,
            "sponsored": 2,
            "ugc": 0
          },
          "nav": {
            "follow": 34,
            "nofollow": 0,
            "sponsored": 0,
            "ugc": 0
          },
          "comments": {
            "follow": 0,
            "nofollow": 0,
            "sponsored": 0,
            "ugc": 0
          }
        },
        "meta": {
          "favicon": "https://cityguide-example.org/favicon-32.png",
          "feeds": [
            "https://cityguide-example.org/feed"
          ],
          "contact": [
            "https://cityguide-example.org/contact"
          ]
        },
        "sections": {
          "article": {
            "links": [
              {
                "url": "https://grand-resorts.example/awards",
                "text": "Grand Resorts",
                "title": "",
                "rel": [
                  "nofollow"
                ],
                "org": {
                  "relationship": "org_competitor"
                }
              }
            ],
            "emails": [
              "press@cityguide-example.org"
            ],
            "phones": [
              "+1 555 0100"
            ],
            "service_accounts": [
              {
                "service": "linkedin",
                "username": "cityguide",
                "label": "City Guide",
                "url": "https://linkedin.com/company/cityguide"
              }
            ]
          },
          "nav": {
            "links": [
              {
                "url": "https://partner-example.com/",
                "text": "Our partner",
                "title": "Partner",
                "rel": [
                  "sponsored"
                ],
                "org": {
                  "relationship": "org_partner"
                }
              }
            ],
            "emails": [
              "hello@cityguide-example.org"
            ],
            "phones": [
              "+1 555 0101"
            ],
            "service_accounts": [
              {
                "service": "twitter",
                "username": "cityguide",
                "label": "",
                "url": "https://x.com/cityguide"
              }
            ]
          },
          "comments": {
            "links": [
              {
                "url": "https://reader-blog-example.net/trip-notes",
                "text": "my trip notes",
                "title": "",
                "rel": [
                  "ugc"
                ],
                "org": {
                  "relationship": "org_partner"
                }
              }
            ],
            "emails": [
              "comments@cityguide-example.org"
            ],
            "phones": [
              "+1 555 0102"
            ],
            "service_accounts": [
              {
                "service": "reddit",
                "username": "cityguide",
                "label": "",
                "url": "https://reddit.com/u/cityguide"
              }
            ]
          }
        }
      }
    }
  ],
  "contacts": {
    "accounts": {
      "head": {
        "facebook": [
          {
            "username": "cityguide",
            "url": "https://www.facebook.com/cityguide",
            "type": "page",
            "count": 14,
            "nsfw": false
          }
        ],
        "x": [
          {
            "username": "cityguide",
            "url": "https://x.com/cityguide",
            "type": "user",
            "count": 21,
            "nsfw": false
          },
          {
            "username": "cityguidedeals",
            "url": "https://x.com/cityguidedeals",
            "type": "user",
            "count": 3,
            "nsfw": false
          }
        ]
      },
      "nav": {
        "instagram": [
          {
            "username": "cityguide",
            "url": "https://www.instagram.com/cityguide",
            "type": "user",
            "count": 18,
            "nsfw": false
          }
        ],
        "x": [
          {
            "username": "cityguide",
            "url": "https://x.com/cityguide",
            "type": "user",
            "count": 17,
            "nsfw": false
          }
        ]
      },
      "article": {
        "linkedin": [
          {
            "username": "grand-resorts",
            "url": "https://www.linkedin.com/company/grand-resorts",
            "type": "page",
            "count": 6,
            "nsfw": false
          }
        ],
        "youtube": [
          {
            "username": "boutiquestays",
            "url": "https://www.youtube.com/@boutiquestays",
            "type": "channel",
            "count": 4,
            "nsfw": false
          }
        ]
      },
      "comments": {
        "onlyfans": [
          {
            "username": "examplecreator",
            "url": "https://onlyfans.com/examplecreator",
            "type": "user",
            "count": 1,
            "nsfw": true
          }
        ],
        "reddit": [
          {
            "username": "tripnotes",
            "url": "https://www.reddit.com/user/tripnotes",
            "type": "user",
            "count": 2,
            "nsfw": false
          }
        ]
      }
    },
    "emails": [
      {
        "email": "press@cityguide-example.org",
        "count": 9
      },
      {
        "email": "hello@cityguide-example.org",
        "count": 4
      }
    ],
    "phones": [
      {
        "phone": "+1 555 0100",
        "count": 7
      },
      {
        "phone": "+1 555 0101",
        "count": 2
      }
    ]
  }
}
```

[Search Results](https://oppalerts.com/docs/the-data/search-results) explains each field.

## Next

- Each tool has its own API page, with every parameter and a full sample response. The [docs home page](https://oppalerts.com/docs/) lists them all.
- Each tool has two routes. For example, `POST /v1/news/search` and `POST /v1/news_search` call the same tool.
- [Authentication and Limits](https://oppalerts.com/docs/api/) lists the errors and the limits.

## Related Pages

- [Authentication and Limits](https://oppalerts.com/docs/api/) The base URL, tokens, daily limits, and errors of the OppAlerts API.
- [Create an API Token](https://oppalerts.com/docs/getting-started/create-an-api-token) Get a token that lets your code or your AI agent call the OppAlerts API and MCP server.
- [Search Results](https://oppalerts.com/docs/the-data/search-results) What you get back for each page that a News Index or Prospect Index search finds.
- [news_search](https://oppalerts.com/docs/mcp/news_search) Search the News Index, a permanent collection of news pages, podcasts, and videos: by semantic similarity, by words in titles and bodies, or both, with date, document type, rank, outbound link, and type score filters.
- [Usage and Daily Limits](https://oppalerts.com/docs/getting-started/usage-and-daily-limits) Know how many calls your account has left today, and see who used them.
