# Events An analytic event is created each time an alert has been triggered or acknowledged. Each event has an associated `task_id` that is the returned value from the response of an alert API call. {% hint style="info" %} Analytic events also have an associated `name` field for correlation that can be programmatically set when an alert is sent via the `/alerts` endpoint. See [Customizing Your Alerts](/docs/relay-alerts-api/customizing-your-alerts.md). {% endhint %} Events can be retrieved through a simple `GET` request to our server into our `/events` endpoint. The `GET` command to send the broadcast should take the following form: ```http GET /subscribers/{id}/api/v1/events Authorization: RelayApiKey {apikey} Content-type: application/json ``` ### Headers and Subscriber ID Path * `apikey` : you should contact Relay to get your API key, as it is not available via self-service. Your key should be included within the Authorization header. Don’t forget to include “RelayApiKey” before your actual key. * `id` : your subscriber ID, which can be found on the Relay Dash through **Help** → **Server Details** under **Subscriber** ### **Optional Query Parameters** * `oldest`: An iso8601 timestamp which defaults to 7 days ago * `limit`: The maximum number of events returned which defaults to 100, the API will return no more than 100 events ### Example The following example shows a curl command that retrieves the oldest analytic event from August 8th from our server. 
$ export subscriber_id=yourcustomersID
$ export apikey=apikey123
$ curl -s -H "authorization: RelayApiKey $apikey" "https://api.relaypro.com/subscribers/$subscriber_id/api/v1/events?oldest=2024-08-08T12:00:30Z&limit=1" | jq
[
 {
  "category": "tasks",
  "content": {"type":"start"},
  "task": {"id": "mCcJawrh3shriXHombQxXA","name": "alerts","task_type": { "major": 1,
  "minor": 4, "name": "alerts", "namespace": "system"}},
  "event_id": "a195f66af5514cacbdbeea09c8e785f6",
  "timestamp": "2024-08-08T18:25:40.923947Z"
 }
]
In the JSON object that gets returned details information about the event and the following fields determine what kind of analytic event it is: * `content`: This field contains information on the event type as well as any external metadata that may have been sent with the event * `type`: This field represents the kind of event that is being returned and can equal the following: * `start`: event for when the alert was triggered * `end`: event for when the alert is completed (through time out, acknowledgement or error) * `acknowledged`: event for when device acknowledges an alert * `timed_out`: event for when an alert times out and no one has acknowledged it * `device`: This field will be present if the event `type` is `acknowledged` and represented the user profile associated with the device that acknowledged the alert * `status`: This field will be present if the event `type` is `end` and the alert has been completed, if the alert was completed without error this should equal `normal` * `task` : The JSON object for the specific event * `id` : Identifier for the task that will be same for every event relevant to the triggered alert (start, acknowledge, time\_out, end), this allows you to track a task throughout each different stages * `name` : Correlation identifier that can be set when event is triggered, defaults to `alert` * `event_id`: An unique identifier for the returned analytic event * `timestamp`: The time at which the event occured The following is an example returned for an event for when an alert was triggered: 
{
  "category": "tasks",
  "content": {  
              "type":"start"
              },
  "task": {
    "id": "mCcJawrh3shriXHombQxXA",
    "name": "alerts",
    "task_type": {
      "major": 1,
      "minor": 4,
      "name": "alerts",
      "namespace": "system"
    }
  },
  "event_id": "XXX",
  "timestamp": "2024-08-08T18:25:40.923947Z"
}
The following is an example returned for an event for when an alert was acknowledged by user 'bob' on a device or virtual account: ```json { "category": "tasks", "content": { "type":"acknowledged", "device": "bob" }, "task": { "id": "9C9AbxNELsQphK9Afhzr6yG6C", "name": "alerts", "task_type": { "major": 1, "minor": 2, "name": "alerts", "namespace": "system" } }, "event_id": "XXX", "timestamp": "2024-08-08T18:25:40.923947Z" } ``` The following is an example returned for an event for when an alert that timed out: 
{
  "category": "tasks",
  "content": {  
              "type":"timed_out"
              },
  "task": {
    "id": "mCcJawrh3shriXHombQxXA",
    "name": "alerts",
    "task_type": {
      "major": 1,
      "minor": 2,
      "name": "alerts",
      "namespace": "system"
    }
  },
  "event_id": "XXX",
  "timestamp": "2024-08-08T18:25:40.923947Z"
}
The following is an example returned for an event for when an alert was completed: 
{
  "category": "tasks",
  "content": {  
              "type":"end",
              "status": "normal"
              },
  "task": {
    "id": "9C9AbxNELsQphK9Afhzr6yG6C",
    "name": "alerts",
    "task_type": {
      "major": 1,
      "minor": 2,
      "name": "alerts",
      "namespace": "system"
    }
  },
  "event_id": "XXX",
  "timestamp": "2024-08-08T18:25:40.923947Z"
}
--- # 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://developer.relaypro.com/docs/relay-events-api.md?ask= ``` 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.