#

🚨 Alerts

The AskNews Alerts API allows you to create and manage alerts for specific topics, news or events. For example, you can create an alert with a query like "Alert me when a protest breaks out in Paris" or "Alert me when Trump talks about the economy."

With the Alerts API you can define the actions to be taken when the alert is triggered, such as generating a report, sending an email or a webhook.

Checkout API reference for more specific API details.

#

Creating an alert

To create an alert, you need to provide a query, cron schedule, and the actions to be taken when the alert is triggered.

Available models for creating alerts are: meta-llama/Meta-Llama-3.1-8B-Instruct, gpt-4o-mini

You can specify the cron schedule in the format minute hour day_of_the_month month day_of_the_week. For example, 0 * * * * will check every hour, whereas 0 0 * * * will check every day at midnight. Check Cron Expression for more details.

If you want to repeat the alert, you can set the repeat field to true. If you don't want to repeat the alert, you can omit the repeat field or set it to false. If repeat is set to false, the alert will be disabled after it is triggered once.

You can use the optional filter_params parameter to target your context based on all the same filter parameters available in /news. This is useful if you want to ask questions about a specific article or set of articles, a specific source, a specific reporting voice, a specific graph, etc. The filter_params parameter is a dictionary that matches the parameters available in the /news endpoint.

If you don't specify the filter_params, the alert will be created with the filter_params that is generated with /autofilter endpoint based on your query.

Create an alert with the following code:

Example response:

{
  "id": "173047ef-0c30-4937-9cdc-e06a7d7a07b0",
  "created_at": "2025-01-15T17:19:36.735136Z",
  "updated_at": "2025-01-15T17:19:43.846455Z",
  "expires_at": null,
  "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "query": "I want to be alerted if the president of the US says something about the economy",
  "cron": "0 * * * *",
  "model": "meta-llama/Meta-Llama-3.1-8B-Instruct",
  "share_link": null,
  "filter_params": {
    "query": "US economy, economic growth, unemployment, inflation, Federal Reserve, GDP, economic indicators, fiscal policy",
    "categories": ["Business", "Finance"],
    "strategy": "latest news"
  },
  "report": {
    "model": "claude-3-5-sonnet-latest"
  },
  "triggers": [
    {
      "action": "email",
      "params": {
        "to": "user@example.com",
        "subject": "Alert: President of the US said something about the economy"
      }
    },
    {
      "action": "webhook",
      "params": {
        "url": "https://example.com/webhook",
        "payload": {
          "content": "{query}\n\n{reasoning}\n\n{report_url}"
        }
      }
    }
  ],
  "always_trigger": false,
  "repeat": false,
  "active": true
}

#

Generating a report for an alert

If you want to generate a report when the alert is triggered, you can specify the report object in the alert. The report object should include the model field which specifies the model to be used to generate the report. If you don't want to generate a report, you can omit the report object or set it to null.

Available models for generating reports are: gpt-4o, gpt-4o-mini, claude-3-5-sonnet-latest, meta-llama/Meta-Llama-3.1-405B-Instruct meta-llama/Meta-Llama-3.3-70B-Instruct

You can also use your customized prompt for the report with the optional prompt parameter. If you don't specify the prompt, it will use the default prompt. Inside your prompt you can use {summaries} placeholder to include the news summaries that will provide the context for the report.

Here is an example of how to specify the prompt in your report object:

{
  "report": {
    "model": "claude-3-5-sonnet-latest",
    "prompt": [
      [
        "system",
        "You are a helpful AI bot. Write a report based on news summaries provided by the user."
      ],
      ["human", "{summaries}"]
    ]
  }
}

#

Alert triggers

Currently, the following triggers are supported:

• Email: Allows you to send an email when the alert is triggered
• Webhook: Allows you to send a webhook when the alert is triggered
• Google Docs: Allows you to create a Google Docs document when the alert is triggered

#

Email Trigger

Email trigger sends an email when the alert is triggered. You can specify the to and subject fields in the params object. If you don't specify the subject, it will use the default subject.

If you requested a report to be generated, the email will include the report as the content. Otherwise it will just show the alert is triggered.

Example:

{
  "action": "email",
  "params": {
    "to": "user@example.com",
    "subject": "Alert: President of the US said something about the economy"
  }
}

#

Webhook Trigger

Webhook trigger sends a webhook when the alert is triggered. You can specify the url, headers and payload fields in the params object. Only url is required, the rest are optional. The request will be sent as a POST request with the payload object as the body.

The payload object can include {query}, {reasoning}, {report}, {share_link} and {report_url} placeholders which will be replaced with the actual values when the webhook is sent.

Example:

{
  "action": "webhook",
  "params": {
    "url": "https://example.com/webhook",
    "headers": {
      "x-api-key": "your-api-key"
    },
    "payload": {
      "query": "{query}",
      "reasoning": "{reasoning}",
      "report_url": "{report_url}"
    }
  }
}

#

Google Docs Trigger

Google Docs trigger creates a Google Docs document when the alert is triggered. You can specify the client_json parameter in the params object. This should be the JSON key file contents of the service account that has access to create Google Docs. The document will be created in the same account. Then using emails parameter you can specify the emails of the users who should have access to the document. The document will be shared with these users.

Example:

{
  "action": "google_docs",
  "params": {
    "client_json": {
      "type": "service_account",
      "project_id": "project-id",
      "private_key_id": "private-key_id",
      "private_key": "private-key",
      "client_email": "client-email",
      "client_id": "client-id",
      "auth_uri": "https://accounts.google.com/o/oauth2/auth",
      "token_uri": "https://oauth2.googleapis.com/token",
      "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
      "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/testuser%40top-glass-445716-r2.iam.gserviceaccount.com",
      "universe_domain": "googleapis.com"
    },
    "emails": ["user1@example.com", "user2@example.com"]
  }
}

#

Listing alerts

You can get a list all of your created alerts with the following code:

(all parameter is optional, you can also paginate the response with page parameter)

Example response:

{
  "items": [
    {
      "id": "173047ef-0c30-4937-9cdc-e06a7d7a07b0",
      "created_at": "2025-01-15T17:19:36.735136Z",
      "updated_at": "2025-01-15T17:19:43.846455Z",
      "expires_at": null,
      "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "query": "I want to be alerted if the president of the US says something about the economy",
      "cron": "0 * * * *",
      "model": "meta-llama/Meta-Llama-3.1-8B-Instruct",
      "share_link": null,
      "filter_params": {
        "query": "US economy, economic growth, unemployment, inflation, Federal Reserve, GDP, economic indicators, fiscal policy",
        "categories": ["Business", "Finance"],
        "strategy": "latest news"
      },
      "report": {
        "model": "claude-3-5-sonnet-latest"
      },
      "triggers": [
        {
          "action": "email",
          "params": {
            "to": "user@example.com",
            "subject": "Alert: President of the US said something about the economy"
          }
        },
        {
          "action": "webhook",
          "params": {
            "url": "https://example.com/webhook",
            "headers": {
              "x-api-key": "your-api-key"
            },
            "payload": {
              "query": "{query}",
              "reasoning": "{reasoning}",
              "report": "{report}"
            }
          }
        }
      ],
      "always_trigger": false,
      "repeat": true,
      "active": true
    }
  ],
  "count": 1,
  "next_page": null,
  "previous_page": null
}

#

Retrieving an alert

You can use the id of an alert to retrieve its details:

#

Retrieving alert logs

You can use the id of an alert to retrieve its logs, which will show the times the alert was triggered or not triggered and the reasoning behind it:

Example response:

{
  "items": [
    {
      "id": "29269ec5-3dd1-4fe8-9b83-2c739dc26fcc",
      "created_at": "2025-01-12T20:29:18.711311Z",
      "alert_id": "53c0eb6d-87b5-436d-9748-f4bdc2e4b343",
      "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "alert": true,
      "reasoning": "The summaries include multiple references to President Biden discussing the economy, particularly in relation to strong jobs reports and economic policies, which directly relates to the user's query.",
      "report": "## Introduction\nYour query was to identify any statements made by the President of the United States regarding the economy based on the provided summaries. This report highlights relevant remarks made by the current president concerning economic conditions and policies.\n\n## Analysis\n\nFrom the summaries, the current President of the United States, Joe Biden, has made several statements regarding the state of the economy:\n\n1. **Strong Labor Market and Economic Performance**:\n   - President Biden highlighted the strength of the US labor market, citing the addition of 256,000 jobs in December and a decrease in the unemployment rate to 4.1%. He emphasized that the US has \"the strongest growth and labor market of all advanced economies\" and noted the creation of over 16.6 million jobs during his term. This performance is seen as a significant achievement, with the unemployment rate reaching its lowest in over 50 years.\n\n2. **Economic Policies and Achievements**:\n   - Biden urged the incoming President-elect Donald Trump to maintain his economic policies, which he claims have transformed the economy and strengthened the middle class. He pointed out the abandonment of \"trickle-down economics\" as a key factor in the economic turnaround. Despite these achievements, Biden acknowledged the challenges posed by inflation, which reached 9% in 2022, impacting voters' perceptions.\n\n3. **Inflation Concerns**:\n   - While Biden celebrated the robust job market, he also acknowledged the ongoing issue of inflation. The Federal Reserve's efforts to manage inflation, including a cycle of interest rate cuts, are noted. However, Biden's administration faces the challenge of balancing economic growth with inflation control.\n\n## Conclusion\n\nPresident Joe Biden has actively communicated his administration's economic successes, particularly in job creation and labor market strength. He has urged continuity in economic policies amidst political transition and recognized the persistent challenge of inflation. As the economy remains resilient, Biden's statements reflect a focus on sustaining growth while addressing inflationary pressures. Monitoring future communications from the President will provide further insights into economic strategies and priorities.",
      "report_url": "https://example.com/report",
      "article_ids": [
        "1b95343c-6817-5e25-9a04-e7bd85238ec5",
        "f1f27e38-7af6-51aa-a6f2-8f3fcc6ac1f3",
        "04729fc6-8f18-5447-a52a-62ba2d4ed468",
        "e6f28fa4-4abd-58d1-bd17-f010c52af4c4",
        "46daf53c-fe42-5d5b-b5ba-a3a50a04f854",
        "be9ac248-3900-5c13-a7c2-c7e4e43abdcd",
        "d64b8472-74dd-51d1-b352-179306c892d8",
        "eae4895d-88f9-5b59-81bc-f7e88dccdc15",
        "1a36b54c-b5f3-5373-94a2-0033a57dacd8",
        "ef06fec7-6a3f-5aa4-b59a-9b0f33405e1d"
      ],
      "webhook": {}
    }
  ],
  "count": 1,
  "next_page": null,
  "previous_page": null
}

#

Updating an alert

You can update alert details using the id of the alert.

It is possible to disable an alert by setting the active field to false. If you want to enable the alert, you can set the active field to true. Disabling an alert will prevent it from being triggered.

#

Deleting an alert

You can delete an alert using the id of the alert: