# 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](https://developer.relaypro.com/docs/relay-alerts-api/customizing-your-alerts).
{% 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.

<pre class="language-sh"><code class="lang-sh"><strong>$ export subscriber_id=yourcustomersID
</strong>$ 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&#x26;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"
 }
]

</code></pre>

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&#x20;
* `timestamp`: The time at which the event occured

The following is an example returned for an event for when an alert was triggered:

<pre class="language-json"><code class="lang-json">{
<strong>  "category": "tasks",
</strong>  "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"
}
</code></pre>

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:

<pre class="language-json"><code class="lang-json">{
<strong>  "category": "tasks",
</strong>  "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"
}
</code></pre>

The following is an example returned for an event for when an alert was completed:

<pre class="language-json"><code class="lang-json">{
<strong>  "category": "tasks",
</strong>  "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"
}
</code></pre>