> For the complete documentation index, see [llms.txt](https://docs.traces.cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.traces.cloud/advanced-event-understanding.md).

# Advanced Event Understanding

## Introduction

Welcome to the Advanced Event Understanding API, a cutting-edge solution for sophisticated event analysis and interpretation. Our API harnesses the power of advanced AI technology to provide deep, real-time insights for your security and surveillance applications. By processing multiple images and associated metadata, our system offers unparalleled event comprehension, enabling you to make informed decisions quickly and efficiently.

## Key Features

* **Efficient Multi-Image Processing**: Analyze 5 or more strategic images per event, providing comprehensive understanding without the need for extensive data transfer.
* **Advanced AI Interpretation**: Extract deep insights from limited visual data, offering sophisticated event analysis that rivals full video processing.
* **Real-time Analysis**: Receive instant results for time-critical decision-making.
* **Flexible Integration**: Seamlessly incorporate our RESTful API into your existing systems.
* **Secure Communication**: Protect your data with robust API key authentication.

## Authentication

All API requests require authentication using an API key. Include your API key in the `x-api-key` header for all requests. If you don't have an API key, you can obtain one by contacting our support team at <support@traces.ai>.

## API Endpoints

{% openapi src="/files/NL9kP5zcWoqnJpwD2lBz" path="/health" method="get" %}
[swagger\_codesamples.json](https://2748832723-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-McYmA310oN--gaDwXjq%2Fuploads%2Fe9wxqsFHWfwLXzVy1Tlp%2Fswagger_codesamples.json?alt=media\&token=89667d40-8b2e-4db7-8316-78382d6b3bc6)
{% endopenapi %}

{% openapi src="/files/0KzCtdmBSZFx3iKCtHZT" path="/event/process" method="post" %}
[swagger\_codesamples.json](https://2748832723-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-McYmA310oN--gaDwXjq%2Fuploads%2FRFsJ723mp5rtGbSZ7IHe%2Fswagger_codesamples.json?alt=media\&token=4821a9a0-7f0a-4b5e-80a5-bf4aae62e01e)
{% endopenapi %}

{% openapi src="/files/0KzCtdmBSZFx3iKCtHZT" path="/event/advanced\_understanding" method="get" %}
[swagger\_codesamples.json](https://2748832723-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-McYmA310oN--gaDwXjq%2Fuploads%2FRFsJ723mp5rtGbSZ7IHe%2Fswagger_codesamples.json?alt=media\&token=4821a9a0-7f0a-4b5e-80a5-bf4aae62e01e)
{% endopenapi %}

## Examples

<div align="left" data-full-width="true"><figure><img src="/files/9yFR6g14zP1JCDuQHTSJ" alt=""><figcaption><p>Input data</p></figcaption></figure></div>

{% code overflow="wrap" fullWidth="true" %}

```json
{
  "status": "completed",
  "result": {
    "event_summary": "A person wearing a light-colored hoodie approaches a black car parked on the side of a street. The person appears to attempt to open the side door, but the car is locked. The person gains entry to the car.",
    "predicted_attributes": {
      "people_descriptions": [
        "light-colored hoodie",
        "dark jeans"
      ],
      "people_actions": [
        "trying to break in"
      ],
      "logos": [
        "None"
      ],
      "vehicle_descriptions": [
        "a black car"
      ],
      "vehicle_actions": [
        "parked"
      ],
      "suspicion_status": "highly suspicious"
    }
  }
}
```

{% endcode %}

## Advanced Features

Our Advanced Event Understanding API offers a range of sophisticated capabilities:

1. **Multi-image Analysis**: Process 5 or more images per event for comprehensive understanding.
2. **Object Detection and Classification**: Identify and categorize objects, people, and vehicles in the scene.
3. **Action Recognition**: Understand and interpret the actions and behaviors of detected entities.
4. **Contextual Analysis**: Evaluate the overall situation and relationships between objects and actions.
5. **Natural Language Summaries**: Generate human-readable descriptions of events for quick comprehension.
6. **Suspicion Assessment**: Automatically evaluate the potential threat level of events.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.traces.cloud/advanced-event-understanding.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.