# Alerts API Queries

Alerts API follows the same [basic principles](/about-graphql.md) as other GraphQL APIs. There are two top-level nodes available: [alerts](/alerts-api/alerts-api-reference.md#alerts-node-signature) and [alert](/alerts-api/alerts-api-reference.md#alert-node-signature). It's possible to specify custom [filters](/alerts-api/alerts-api-queries/filtering-and-sorting.md#filtering) and [sort order](/alerts-api/alerts-api-queries/filtering-and-sorting.md#sorting) to retrieve a required subset of Alerts. Larger workflows could benefit from using [pagination](/alerts-api/alerts-api-queries/pagination.md) when the number of Alerts returned doesn't fit into a single API response.

You may find all entity types defined in [Alerts API Reference](/alerts-api/alerts-api-reference.md).

### Examples

#### Find Alerts by Company ID:

```graphql
query findAlerts($id: ID!) {
  alerts(
    where: {
      # Will filter for both "company.id" 
      # and "relatedCompanies.id"
      company: {
        id: { eq: $id }
      }
    }
  ) {
    id
    title
    text
    company {
      id
      displayName
    }
    relatedCompanies {
      id
      displayName
    }
  }
}
```

Alerts have two main fields storing the Company data:

* `company`
  * Represents the specific company that is a subject of a given Alert. It's present on the Alerts describing events that happened to that particular Company. For example, headcount change or financial metrics change. If Alert describes an event that is generally related to multiple companies, this field will be `null`, to process the list of related companies, please refer to the field below.
* `relatedCompanies`
  * Represents all the companies related to the event described by the Alert. Will contain a single item for events that are specific to the given Company or multiple items for more general events affecting multiple Companies at once.

#### Find Alerts by dataset and class

```graphql
query findAlerts($dataset: String!, $class: String!) {
  alerts(
    where: {
      dataset: { eq: $dataset },
      class: { code: { eq: $class } }
    }
  ) {
    id
    title
    text
    dataset 
    class {
      code
      label
    }
  }
}
```

Dataset examples:

* `news` for Alerts about news articles describing a certain change for a particular Company
* `employees` for Alerts describing changes in the employee count for a particular Company
* `news_commodities` for Alerts representing news on certain Commodities
* `balance_sheet` 
* `news_events`
* `pnl`
* `jobs`

Class examples:

`awards`, `bankruptcy`, `commodity`, `conference`, `cybersecurity`, `environmental_impact`, `epidemic`, `financial_changes`, `...`

{% hint style="info" %}
Please, note that particular dataset and class availability depends on your contractual agreement with Craft. Reach out to <sales@craft.co> for additional details.
{% endhint %}

#### Find Alerts for a particular date range

```graphql
query findAlerts($from: String!, $to: String!) {
  alerts(
    where: {
      publishedAt: {
        gte: $from
        lte: $to 
      }
    }
  ) {
    id
    title
    text
    company {
      displayName
    }
    publishedAt
  }
}
```

#### Find a single Alert by its id

```graphql
query findAlert($id: ID) {
  alert(id: $id) {
    id
    title
    text
  }
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.craft.co/alerts-api/alerts-api-queries.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.