### Example Query with Specific Service and Start Time

Source: https://docs.jumpcloud.com/api/insights/directory/1.0/index.html

An example of a JSON body for querying RADIUS events starting from a specific date and time. Ensure the 'start_time' is in RFC3339 format.

```json
{
    "service": [
        "radius"
    ],
    "start_time": "2020-01-01T14:00:00Z"
}
```

--------------------------------

### Example Request to Retrieve All Events

Source: https://docs.jumpcloud.com/api/insights/directory/1.0/index.html

This example shows how to make a POST request to the Directory Insights API to retrieve all events starting from a specific time. Ensure you replace 'REPLACE_KEY_VALUE' with your actual API key.

```curl
curl -X POST \
  -H 'x-api-key: REPLACE_KEY_VALUE' \
  -H 'Content-Type: application/json' \
  --data '{"service": ["all"], "start_time": "2020-03-03T14:00:00Z"}' \
  --url https://api.jumpcloud.com/insights/directory/v1/events

```

--------------------------------

### Request Multi-Tenant Portal Events Only

Source: https://docs.jumpcloud.com/api/insights/directory/1.0/index.html

This example shows how to request events specifically from the multi-tenant portal by including the 'x-provider-id' header.

```bash
curl -X POST -H 'x-api-key: REPLACE_KEY_VALUE' -H 'x-provider-id: YOUR_PROVIDER_KEY_HERE' -H 'Content-Type: application/json' --data '{"service": ["all"], "start_time": "2020-03-03T14:00:00Z"}' https://api.jumpcloud.com/insights/directory/v1/events
```

--------------------------------

### Sample Response for Event Query (200 OK)

Source: https://docs.jumpcloud.com/api/insights/directory/1.0/index.html

An example of a successful response when querying events, returning an array of event objects.

```json
[
  { }
]
```

--------------------------------

### Example Request for MSPs to Retrieve Events for One Organization

Source: https://docs.jumpcloud.com/api/insights/directory/1.0/index.html

This example demonstrates how Managed Service Providers can query client organization events. It requires an MSP admin API key and the client organization ID. Replace 'REPLACE_KEY_VALUE' and 'ADMINISTERED_ORG_ID' with your credentials.

```curl
curl -X POST -H 'x-api-key: REPLACE_KEY_VALUE' -H 'x-org-id: ADMINISTERED_ORG_ID' -H 'Content-Type: application/json' --data '{"service": ["all"], "start_time": "2020-03-03T14:00:00Z"}' https://api.jumpcloud.com/insights/directory/v1/events

```

--------------------------------

### API Response Header Metadata Example

Source: https://docs.jumpcloud.com/api/insights/directory/1.0/index.html

This example shows the structure of HTTP response headers, including result count, limit, sort order, and pagination tokens.

```json
{
  "X-Result-Count": 1000,
  "X-Limit": 1000,
  "X-Sort": "ASC",
  "X-Search_after": [
    1576181718000,
    "DZrPyW8BNsa9iKWoOm7h"
  ],
  "X-Request-Id": "f5b277fc-7b0b-4c1e-9bee-c5ea1d79302f"
}
```

--------------------------------

### Event Distinct Query Payload Example

Source: https://docs.jumpcloud.com/api/insights/directory/1.0/index.html

An example JSON payload for the EventDistinctQuery endpoint, specifying time ranges, services, and the field to query.

```json
{
  "end_time": "2019-08-24T14:15:22Z",
  "service": [
    "alerts"
  ],
  "start_time": "2019-08-24T14:15:22Z",
  "field": "string",
  "search_term": {
    "and": { },
    "not": { },
    "or": { }
}

}

```

--------------------------------

### Example Admin Login Attempt Response

Source: https://docs.jumpcloud.com/api/insights/directory/1.0/index.html

A sample JSON response object for an 'admin_login_attempt' event. The response includes details about the event, resource, client IP, and user agent.

```json
{
    "geoip": {
        "timezone": "America/Denver",
        "country_code2": "US",
        "continent_code": "NA",
        "region_name": "Colorado",
        "region_code": "CO"
    },
    "event_type": "admin_login_attempt",
    "resource": {
        "id": "5ce434e77128503e528e747c",
        "type": "admin",
        "email": "jane.doe@gmail.com"
    },
    "provider": null,
    "success": true,
    "organization": "6ce434e87128303e528e747b",
    "@version": "1",
    "mfa": true,
    "client_ip": "73.203.76.115",
    "id": "5e95d60b05e8907888c4e009",
    "useragent": {
        "patch": "4044",
        "minor": "0",
        "major": "81",
        "os": "Mac OS X",
        "build": "",
        "os_minor": "15",
        "os_major": "10",
        "name": "Chrome",
        "os_name": "Mac OS X",
        "device": "Other"
    },
    "timestamp": "2020-04-14T15:26:03.218Z"
}
```

--------------------------------

### Nested Object Event Data Example

Source: https://docs.jumpcloud.com/api/insights/directory/1.0/index.html

Example of event data containing nested objects. This demonstrates the structure of data that might be returned by the API.

```json
{
  "error_message": null,
  "auth_type": "eap",
  "nas_mfa_state": "DISABLED",
  "eap_type": "MSCHAPv2",
  "outer": {
    "error_message": null,
    "eap_type": "PEAP",
    "username": "zezeye21"
  },
  "mfa": false,
  "mfa_meta": {
    "type": "none"
  },
  "success": true,
  "organization": "5dc058bc3f53f95e3972f03f",
  "client_ip": "209.235.170.66",
  "id": "ED0ED2C3-0524-3263-BE5B-68C02B70986E",
  "username": "zezeye21",
  "timestamp": "2019-12-12T20:15:15Z"
}
```

--------------------------------

### Advanced Search: OR with Multiple Fields and List Values

Source: https://docs.jumpcloud.com/api/insights/directory/1.0/index.html

Construct complex OR queries where multiple fields can match any value from their respective lists. This example returns events matching either username criteria OR client_ip criteria.

```json
{
  "service": [
    "radius"
  ],
  "start_time": "2020-01-01T14:00:00Z",
  "search_term": {
    "or": [
      {
        "username": [
          "root",
          "admin"
        ]
      },
      {
        "client_ip": [
          "1.2.3.4",
          "2.3.4.5"
        ]
      }
    ]
  }
}
```

--------------------------------

### Get List of Report Metadata

Source: https://docs.jumpcloud.com/api/insights/directory/1.0/index.html

Retrieve a list of report metadata. You can sort the results by various parameters like creation time, expiration, or status.

```shell
curl --request GET \
  --url 'https://api.jumpcloud.com/insights/directory/v1/reports?sort=SOME_STRING_VALUE' \
  --header 'x-api-key: REPLACE_KEY_VALUE'
```

--------------------------------

### Supported Search Operators

Source: https://docs.jumpcloud.com/api/insights/directory/1.0/index.html

Examples of various search operators supported by the Directory Insights API, including string comparisons, numeric comparisons, and timestamp comparisons.

```APIDOC
## Supported Search Operators

This section provides examples of how to use different search operators within the `search_term` of the Directory Insights API.

### `startsWith` (prefix)

```json
{
  "service": ["all"],
  "start_time": "2026-05-01T00:00:00Z",
  "search_term": {
    "and": [
      {
        "field": "username",
        "operator": "startsWith",
        "value": "adm"
      }
    ]
  }
}
```

### `endsWith` (literal suffix)

```json
{
  "service": ["all"],
  "start_time": "2026-05-01T00:00:00Z",
  "search_term": {
    "and": [
      {
        "field": "hostname",
        "operator": "endsWith",
        "value": ".corp"
      }
    ]
  }
}
```

### `lt` / `gt` / `lte` / `gte` (numeric comparisons)

```json
{
  "service": ["all"],
  "start_time": "2026-05-01T00:00:00Z",
  "search_term": {
    "and": [
      {
        "field": "doc_version",
        "operator": "gte",
        "value": 2
      }
    ]
  }
}
```

### `before` / `after` (timestamp comparisons)

```json
{
  "service": ["all"],
  "start_time": "2026-05-01T00:00:00Z",
  "search_term": {
    "and": [
      {
        "field": "timestamp",
        "operator": "after",
        "value": "2026-05-07T00:00:00Z"
      }
    ]
  }
}
```

### `in` (value in list)

```json
{
  "service": ["all"],
  "start_time": "2026-05-01T00:00:00Z",
  "search_term": {
    "and": [
      {
        "field": "event_type",
        "operator": "in",
        "value": ["login", "logout"]
      }
    ]
  }
}
```

### `not_in` (value not in list)

```json
{
  "service": ["all"],
  "start_time": "2026-05-01T00:00:00Z",
  "search_term": {
    "and": [
      {
        "field": "event_type",
        "operator": "not_in",
        "value": ["login", "logout"]
      }
    ]
  }
}
```

**Note:** The following attributes are not supported for searching: `"changes"`, `"useragent"`, and `"system_timestamp"`.
```

--------------------------------

### Retrieve Directory Events

Source: https://docs.jumpcloud.com/api/insights/directory/1.0/index.html

This endpoint retrieves directory event logs. You can specify the services to query and a start time for the logs. An API key is required for authentication, and an optional organization ID can be provided for Managed Service Providers.

```APIDOC
## POST /insights/directory/v1/events

### Description
Retrieves directory event logs. Supports filtering by service and start time. Requires authentication via API key and optionally accepts an organization ID for MSPs.

### Method
POST

### Endpoint
https://api.jumpcloud.com/insights/directory/v1/events

### Parameters
#### Headers
- **x-api-key** (string) - Required - Your JumpCloud API key.
- **x-org-id** (string) - Optional - The organization ID for Managed Service Providers.
- **Content-Type** (string) - Required - Must be set to application/json.

#### Request Body
- **service** (array of strings) - Required - Specifies the services to retrieve events from. Example: ["all"], ["directory"], ["saml"].
- **start_time** (string) - Required - The start time for the event logs in ISO 8601 format. Example: "2020-03-03T14:00:00Z".

### Request Example
```json
{
  "service": ["all"],
  "start_time": "2020-03-03T14:00:00Z"
}
```

### Response
#### Success Response (200)
- **event_data** (object) - Contains the retrieved event logs.

#### Response Example
```json
{
  "event_data": [
    {
      "timestamp": "2023-10-27T10:00:00Z",
      "eventType": "Directory Event",
      "details": {
        "user": "admin@example.com",
        "action": "User Login",
        "ipAddress": "192.168.1.1"
      }
    }
  ]
}
```
```

--------------------------------

### POST /events

Source: https://docs.jumpcloud.com/api/insights/directory/1.0/index.html

Queries event logs from the Directory Insights API. Supports filtering by service and start time. Can accept multiple organization IDs via the x-org-id header.

```APIDOC
## POST /events

### Description
Queries event logs from the Directory Insights API. Supports filtering by service and start time. Can accept multiple organization IDs via the x-org-id header.

### Method
POST

### Endpoint
https://api.jumpcloud.com/insights/directory/v1/events

### Parameters
#### Headers
- **x-api-key** (string) - Required - Your JumpCloud API key.
- **x-org-id** (string) - Required - The ID of the organization to query. Can be specified multiple times for multi-organization queries.
- **x-provider-id** (string) - Optional - Used for requesting multi-tenant portal events only.

#### Request Body
- **service** (array of strings) - Required - A list of services to query logs from. Valid values include: `access_management`, `alert`, `all`, `directory`, `ldap`, `mdm`, `notifications`, `password_manager`, `object_storage`, `radius`, `reports`, `software`, `sso`, `systems`, `asset_management`, `genai`, `aigw`, `di_events`.
- **start_time** (string) - Required - An RFC 3339 formatted UTC date (e.g., `2020-03-03T14:00:00Z`) specifying the start of the time range for the query.

### Request Example
```json
{
    "service": [
        "radius"
    ],
    "start_time": "2020-01-01T14:00:00Z"
}
```

### Response
#### Success Response (200)
- Returns a JSON array of event objects. Each object contains details about a specific event, including timestamp, event type, resource information, success status, and more. The exact fields may vary depending on the event type.

#### Response Example
```json
{
    "geoip": {
        "timezone": "America/Denver",
        "country_code2": "US",
        "continent_code": "NA",
        "region_name": "Colorado",
        "region_code": "CO"
    },
    "event_type": "admin_login_attempt",
    "resource": {
        "id": "5ce434e77128503e528e747c",
        "type": "admin",
        "email": "jane.doe@gmail.com"
    },
    "provider": null,
    "success": true,
    "organization": "6ce434e87128303e528e747b",
    "@version": "1",
    "mfa": true,
    "client_ip": "73.203.76.115",
    "id": "5e95d60b05e8907888c4e009",
    "useragent": {
        "patch": "4044",
        "minor": "0",
        "major": "81",
        "os": "Mac OS X",
        "build": "",
        "os_minor": "15",
        "os_major": "10",
        "name": "Chrome",
        "os_name": "Mac OS X",
        "device": "Other"
    },
    "timestamp": "2020-04-14T15:26:03.218Z"
}
```
```

--------------------------------

### Query Distinct Field Values

Source: https://docs.jumpcloud.com/api/insights/directory/1.0/index.html

Use this endpoint to get a list of unique values for a specified field within a given time range and service. Requires an API key and organization ID.

```shell
curl -X POST 'https://api.jumpcloud.com/insights/directory/v1/events/distinct' -H 'Content-Type: application/json' -H 'x-api-key: REPLACE_KEY_VALUE' --data '{"service": ["all"], "start_time": "2021-07-14T23:00:00Z", "end_time": "2021-07-28T14:00:00Z", "sort": "DESC", "field": "event_type"}'

```

--------------------------------

### Get a list of report metadata

Source: https://docs.jumpcloud.com/api/insights/directory/1.0/index.html

Retrieves an ordered list of report metadata. Supports sorting by various fields like creation time, expiration, and status.

```APIDOC
## GET /insights/directory/v1/reports

### Description
Retrieves an ordered list of report metadata. Supports sorting by various fields like creation time, expiration, and status.

### Method
GET

### Endpoint
https://api.jumpcloud.com/insights/directory/v1/reports

### Parameters
#### Query Parameters
- **sort** (string) - Optional - Enum: "CREATED_AT" "EXPIRATION" "REQUESTER_EMAIL" "STATUS" "TYPE" "UPDATED_AT" "-CREATED_AT" "-EXPIRATION" "-REQUESTER_EMAIL" "-STATUS" "-TYPE" "-UPDATED_AT" - Sort type and direction. Default sort is descending, prefix with - to sort ascending.

### Response
#### Success Response (200)
- **Array of report metadata**

#### Response Example
```json
[
  {
    "artifacts": [
      {
        "format": "CSV",
        "id": "string"
      }
    ],
    "created_at": "string",
    "expiration": "string",
    "id": "string",
    "parameters": [
      {}
    ],
    "requester_email": "string",
    "requester_id": "string",
    "status": "PENDING",
    "type": "browser-patch-policy",
    "updated_at": "string"
  }
]
```
```

--------------------------------

### Note on JSON Term Repetition

Source: https://docs.jumpcloud.com/api/insights/directory/1.0/index.html

Illustrates that JSON does not allow a term to be repeated for the same field within a query. This example shows an invalid attempt to specify multiple values for 'username' using separate objects in an OR clause.

```json
{
  "service": [
    "radius"
  ],
  "start_time": "2020-01-01T14:00:00Z",
  "search_term": {
    "or": [
      {
        "username": "root"
      },
      {
        "username": "admin"
      }
    ]
  }
}
```

--------------------------------

### Execute POST Request Using Local File

Source: https://docs.jumpcloud.com/api/insights/directory/1.0/index.html

Demonstrates how to execute a POST request by referencing a local file containing the JSON body. This is useful for managing complex query structures.

```bash
curl -X POST -H 'x-api-key: REPLACE_KEY_VALUE' -d @./simple-query.txt https://api.jumpcloud.com/insights/directory/v1/events
```

--------------------------------

### Sample cURL Request for Querying Events

Source: https://docs.jumpcloud.com/api/insights/directory/1.0/index.html

Demonstrates how to use cURL to send a POST request to the events endpoint. Includes essential headers and a sample JSON payload for filtering events.

```shell
curl -X POST 'https://api.jumpcloud.com/insights/directory/v1/events' -H 'Content-Type: application/json' -H 'x-api-key: REPLACE_KEY_VALUE' --data '{"service": ["all"], "start_time": "2021-07-14T23:00:00Z", "end_time": "2021-07-28T14:00:00Z", "sort": "DESC", "fields": ["timestamp", "event_type", "initiated_by", "success", "client_ip", "provider", "organization"]}'
```

--------------------------------

### Filter by End Time

Source: https://docs.jumpcloud.com/api/insights/directory/1.0/index.html

Limit returned rows to those between a specified start and end time. The `end_time` field is optional but must appear after `start_time`.

```json
{
  "service": [
    "radius"
  ],
  "start_time": "2020-01-01T14:00:00Z",
  "end_time": "2020-02-01T14:00:00Z"
}
```

--------------------------------

### Search by Username Prefix

Source: https://docs.jumpcloud.com/api/insights/directory/1.0/index.html

Use the 'startsWith' operator to find entries where the username begins with a specific prefix.

```json
{
  "service": ["all"],
  "start_time": "2026-05-01T00:00:00Z",
  "search_term": {
    "and": [
      {
        "field": "username",
        "operator": "startsWith",
        "value": "adm"
      }
    ]
  }
}
```

--------------------------------

### Download a Report

Source: https://docs.jumpcloud.com/api/insights/directory/1.0/index.html

Download a specific report artifact using its report ID and artifact ID. Ensure you replace placeholders with actual IDs and your API key.

```shell
curl --request GET \
  --url https://api.jumpcloud.com/insights/directory/v1/reports/{report_id}/artifacts/{artifact_id}/content \
  --header 'x-api-key: REPLACE_KEY_VALUE'
```

--------------------------------

### Request a Report (Shell)

Source: https://docs.jumpcloud.com/api/insights/directory/1.0/index.html

Use this cURL command to make a POST request to the JumpCloud API to generate a report. Replace REPLACE_KEY_VALUE with your actual API key.

```shell
curl --request POST \
  --url https://api.jumpcloud.com/insights/directory/v1/reports/{report_type} \
  --header 'x-api-key: REPLACE_KEY_VALUE'
```

--------------------------------

### Report Metadata Response Sample

Source: https://docs.jumpcloud.com/api/insights/directory/1.0/index.html

This is a sample response containing an array of report metadata objects. Each object includes details about the report's artifacts, creation time, status, and type.

```json
[
  {
    "artifacts": [
      {
        "format": "CSV",
        "id": "string"
}
],
    "created_at": "string",
    "expiration": "string",
    "id": "string",
    "parameters": [
      {
}
],
    "requester_email": "string",
    "requester_id": "string",
    "status": "PENDING",
    "type": "browser-patch-policy",
    "updated_at": "string"
}

]
```

--------------------------------

### Querying Nested Object Fields

Source: https://docs.jumpcloud.com/api/insights/directory/1.0/index.html

Use dot notation (e.g., 'outer.eap_type') to query fields within nested objects. This example filters for events where the nested 'eap_type' is 'PEAP'.

```json
{
  "service": [
    "radius"
  ],
  "start_time": "2020-01-01T14:00:00Z",
  "search_term": {
    "and": [
      {
        "outer.eap_type": "PEAP"
      }
    ]
  }
}
```

--------------------------------

### Select Specific Fields

Source: https://docs.jumpcloud.com/api/insights/directory/1.0/index.html

Limit returned fields to improve download times for large datasets. An empty or invalid fields list will result in a 400 error.

```json
{
  "service": [
    "radius"
  ],
  "start_time": "2020-01-01T14:00:00Z",
  "fields": [
    "timestamp",
    "username",
    "client_ip",
    "success"
  ]
}
```

--------------------------------

### Request Multiple Organizations

Source: https://docs.jumpcloud.com/api/insights/directory/1.0/index.html

Use this to query events across multiple organizations by including multiple 'x-org-id' headers. There is no limit to the number of organization IDs that can be passed.

```bash
curl -X POST -H 'x-api-key: REPLACE_KEY_VALUE' -H 'x-org-id: ADMINISTERED_ORG_ID_A' -H 'x-org-id: ADMINISTERED_ORG_ID_B' -H 'x-org-id: ADMINISTERED_ORG_ID_C' -H 'Content-Type: application/json' --data '{"service": ["all"], "start_time": "2020-03-03T14:00:00Z"}' https://api.jumpcloud.com/insights/directory/v1/events
```

--------------------------------

### Search by Hostname Suffix

Source: https://docs.jumpcloud.com/api/insights/directory/1.0/index.html

Use the 'endsWith' operator to find entries where the hostname ends with a specific suffix.

```json
{
  "service": ["all"],
  "start_time": "2026-05-01T00:00:00Z",
  "search_term": {
    "and": [
      {
        "field": "hostname",
        "operator": "endsWith",
        "value": ".corp"
      }
    ]
  }
}
```

--------------------------------

### Count Matching Event Rows Response

Source: https://docs.jumpcloud.com/api/insights/directory/1.0/index.html

This is a sample response for a successful count of matching event rows.

```json
{
  "count": 0

}
```

--------------------------------

### Search Failed Authentications by Username

Source: https://docs.jumpcloud.com/api/insights/directory/1.0/index.html

Use this query to find failed authentication events for a specific user. It filters by success status and checks both the 'initiated_by.username' and 'username' fields.

```json
{
  "service": [
    "radius"
  ],
  "start_time": "2020-01-01T14:00:00Z",
  "search_term": {
    "and": [
      {
        "success": "false"
      },
      {
        "or": [
          {
            "initiated_by.username": "paul"
          },
          {
            "username": "paul"
          }
        ]
      }
    ]
  }
}
```

--------------------------------

### Query Event Counts by Time Interval

Source: https://docs.jumpcloud.com/api/insights/directory/1.0/index.html

This endpoint allows you to retrieve counts of events bucketed by a specified time interval. It requires service, time range, timezone, and interval details.

```shell
curl -X POST 'https://api.jumpcloud.com/insights/directory/v1/events/interval' -H 'Content-Type: application/json' -H 'x-api-key: REPLACE_KEY_VALUE' --data '{"service": ["all"], "start_time": "2021-07-14T23:00:00Z", "end_time": "2021-07-28T14:00:00Z", "timezone": "-0500", "interval_unit": "h", "interval_value": "2"}'

```

--------------------------------

### Selecting Specific Fields

Source: https://docs.jumpcloud.com/api/insights/directory/1.0/index.html

Limit the fields returned in the response by providing a list of desired fields in the `fields` array. This can improve download times for large datasets.

```APIDOC
## GET /insights/directory

### Description
Retrieves event data, allowing for specific fields to be returned to optimize performance.

### Method
GET

### Endpoint
/insights/directory

### Parameters
#### Query Parameters
- **fields** (array) - Optional - A list of strings specifying which fields to include in the response. If empty or contains unknown fields, a 400 error is returned.
- **start_time** (string) - Required - The start of the time range for the events (ISO 8601 format).
- **end_time** (string) - Optional - The end of the time range for the events (ISO 8601 format). Must be after `start_time`.
- **search_term** (object) - Optional - Criteria for advanced searching.

### Request Example
```json
{
  "service": [
    "radius"
  ],
  "start_time": "2020-01-01T14:00:00Z",
  "fields": [
    "timestamp",
    "username",
    "client_ip",
    "success"
  ]
}
```

### Response
#### Success Response (200)
- **timestamp** (string) - The time the event occurred.
- **username** (string) - The username associated with the event.
- **client_ip** (string) - The client IP address from which the event originated.
- **success** (boolean) - Indicates whether the event was successful.
```

--------------------------------

### Request a report

Source: https://docs.jumpcloud.com/api/insights/directory/1.0/index.html

Request a JumpCloud report to be generated asynchronously. The report type must be specified in the path.

```APIDOC
## POST /insights/directory/v1/reports/{report_type}

### Description
Request a JumpCloud report to be generated asynchronously. The report type must be specified in the path.

### Method
POST

### Endpoint
https://api.jumpcloud.com/insights/directory/v1/reports/{report_type}

### Parameters
#### Path Parameters
- **report_type** (string) - Required - Enum: "browser-patch-policy", "os-patch-policy", "os-version", "software-inventory", "user-account-health", "users-to-devices", "users-to-directories", "users-to-ldap-servers", "users-to-radius-servers", "users-to-sso-applications", "users-to-user-groups" - Report Type

#### Request Body
None

### Response
#### Success Response (202)
- **artifacts** (array) - List of artifacts generated for the report.
  - **format** (string) - The format of the artifact (e.g., CSV).
  - **id** (string) - The unique identifier for the artifact.
- **created_at** (string) - Timestamp when the report was created.
- **expiration** (string) - Timestamp when the report will expire.
- **id** (string) - The unique identifier for the report.
- **parameters** (array) - Parameters used for generating the report.
- **requester_email** (string) - Email of the user who requested the report.
- **requester_id** (string) - ID of the user who requested the report.
- **status** (string) - The current status of the report (e.g., PENDING).
- **type** (string) - The type of the report.
- **updated_at** (string) - Timestamp when the report was last updated.

#### Response Example
```json
{
  "artifacts": [
    {
      "format": "CSV",
      "id": "string"
    }
  ],
  "created_at": "string",
  "expiration": "string",
  "id": "string",
  "parameters": [
    {}
  ],
  "requester_email": "string",
  "requester_id": "string",
  "status": "PENDING",
  "type": "browser-patch-policy",
  "updated_at": "string"
}
```

### Error Handling
- **400**: Invalid parameter
- **401**: Unauthorized (Invalid API Key)
- **403**: User role does not have access to Reports
- **500**: Technical difficulties processing your request
```

--------------------------------

### Count Directory Events

Source: https://docs.jumpcloud.com/api/insights/directory/1.0/index.html

Use this endpoint to count directory events based on specified criteria. Ensure you replace 'REPLACE_KEY_VALUE' with your actual API key.

```shell
curl -X POST 'https://api.jumpcloud.com/insights/directory/v1/events/count' -H 'Content-Type: application/json' -H 'x-api-key: REPLACE_KEY_VALUE' --data '{"service": ["all"], "start_time": "2021-07-14T23:00:00Z", "end_time": "2021-07-28T14:00:00Z", "sort": "DESC", "fields": ["timestamp", "event_type", "initiated_by", "success", "client_ip", "provider", "organization"]}'
```

--------------------------------

### Query event counts by bucketed by a time interval

Source: https://docs.jumpcloud.com/api/insights/directory/1.0/index.html

Query the API for a list of event counts, bucketed by a specified time interval, within a given time range and for selected services.

```APIDOC
## POST /events/interval

### Description
Query the API for a list of counts by bucketed by a time interval.

### Method
POST

### Endpoint
https://api.jumpcloud.com/insights/directory/v1/events/interval

### Parameters
#### Query Parameters
- **service** (string[]) - Required - Service name to query. Enum: "alerts", "all", "directory", "ldap", "mdm", "notifications", "object_storage", "password_manager", "radius", "reports", "saas_app_management", "software", "sso", "systems", "access_management", "asset_management", "workflows", "genai", "aigw", "di_events"
- **start_time** (string) - Required - Query start time, UTC in RFC3339 format
- **end_time** (string) - Optional - Query end time, UTC in RFC3339 format
- **timezone** (string) - Optional - Timezone for the interval
- **interval_unit** (string) - Required - Unit of the interval (e.g., 'h' for hour, 'd' for day)
- **interval_value** (string) - Required - Value of the interval

### Request Example
```json
{
  "service": ["all"],
  "start_time": "2021-07-14T23:00:00Z",
  "end_time": "2021-07-28T14:00:00Z",
  "timezone": "-0500",
  "interval_unit": "h",
  "interval_value": "2"
}
```

### Response
#### Success Response (200)
List of event counts by time interval.

#### Error Responses
- **400** Invalid/unknown query JSON body
- **401** Unauthorized (Invalid API Key)
- **402** Directory Insights is not enabled for your organization
- **500** Technical difficulties processing your request
```

--------------------------------

### Operator-based Search - Generic Structure

Source: https://docs.jumpcloud.com/api/insights/directory/1.0/index.html

Template for constructing operator-based search terms. Specify the field, operator, and value for precise querying.

```json
{
  "field": "<event_field_name>",
  "operator": "<operator>",
  "value": "<string | number | boolean | timestamp | array>"
}
```

--------------------------------

### JSON POST Request Body Structure

Source: https://docs.jumpcloud.com/api/insights/directory/1.0/index.html

Defines the required fields for a POST request to the API's /events endpoint. 'service' specifies the type of logs, and 'start_time' sets the earliest event time.

```json
{
    "service": [
        "service name"
    ],
    "start_time": "RFC 3339 date"
}
```

--------------------------------

### API Request for Next Page of Results

Source: https://docs.jumpcloud.com/api/insights/directory/1.0/index.html

To retrieve subsequent pages of data, reissue the original query and include the 'search_after' field with the value from the 'X-Search_after' response header.

```json
{
  "service": [
    "radius"
  ],
  "start_time": "2020-01-01T14:00:00Z",
  "search_after": [
    1576181718000,
    "DZrPyW8BNsa9iKWoOm7h"
  ]
}
```

--------------------------------

### Operator-based Search - Equals (eq)

Source: https://docs.jumpcloud.com/api/insights/directory/1.0/index.html

Use explicit operators for advanced search criteria. The 'eq' operator performs an exact match.

```json
{
  "service": ["all"],
  "start_time": "2026-05-01T00:00:00Z",
  "search_term": {
    "and": [
      {
        "field": "username",
        "operator": "eq",
        "value": "root"
      }
    ]
  }
}
```

--------------------------------

### Advanced Search: Compound Logic

Source: https://docs.jumpcloud.com/api/insights/directory/1.0/index.html

Explains how to construct complex queries using AND and OR logical operators within the `search_term`.

```APIDOC
## Advanced Search: Compound Logic

The `search_term` section supports complex queries using `and` and `or` logical operators. All conditions within `and` or `or` should be comma-separated JSON objects enclosed in a JSON array `[]`.
```

--------------------------------

### Directory Attributes

Source: https://docs.jumpcloud.com/api/insights/directory/1.0/index.html

This section details the fields available for querying directory events. Each field represents a specific attribute of an event, such as its ID, type, timestamp, resource involved, and initiation details.

```APIDOC
## Directory Attributes

This section details the fields available for querying directory events. Each field represents a specific attribute of an event, such as its ID, type, timestamp, resource involved, and initiation details.

### Fields

- **id** (uuid) - Unique ID for the event.
- **correlation** (object) - Details for a background process or parent event that can be used to correlate related events.
- **event_type** (string) - Event type.
- **timestamp** (RFC3339 Timestamp) - Timestamp of when the event occurred (UTC).
- **resource** (object) - Resource that changed or attempted the login.
- **system_group** (object) - Object that contains the closest device/system group involved in the event.
- **organization** (keyword) - Organization that the user belongs to.
- **changes** (Nested objects) - List of changes made in the request. You cannot search on the contents of this field.
- **initiated_by** (object) - Object that describes who initiated the request.
- **association** (object) - Object that describes a change in association, such as adding a user to a group.
- **client_ip** (string) - IP address that the request came from.
- **useragent** (object) - User agent information for the browser that submitted the request. You cannot search on the contents of this field.
- **auth_method** (string) - Session = console, api-key = api-key
- **success** (boolean) - Denotes whether a login attempt was successful.
- **mfa** (boolean) - Denotes whether MFA was used on an authentication attempt.
- **mfa_meta** (object) - Object that contains metadata around MFA authentication such as the type of MFA.
- **geoip** (object) - Geo IP information for the IP address that made the request.
- **provider** (string) - The org ID of the provider if the org is a provider org.
- **service** (string) - Service that the event originated from.
- **auth_context** (object) - Object for authentication context including factors used, device information if cert was present, and policies that were applied.
- **application** (object) - Information for the application that the event was initiated for.
- **idm_client_id** (string) - The client ID for the Identity Management integration
- **error_message** (string) - Error details.
- **message_chain** (object) - Results detail for each event
- **@version** (integer) - The schema version for the document object.
- **system** (object) - The object that describes the system.
- **target_resource** (object) - The object that describes the target_resource.
```

--------------------------------

### AND Search Criteria

Source: https://docs.jumpcloud.com/api/insights/directory/1.0/index.html

Query events matching all criteria in the 'and' list. Field names cannot be repeated. Complex searches may cause HTTP 500 errors.

```json
{
  "service": [
    "radius"
  ],
  "start_time": "2020-01-01T14:00:00Z",
  "search_term": {
    "and": [
      {
        "username": "root"
      },
      {
        "client_ip": "1.2.3.4"
      }
    ]
  }
}
```

--------------------------------

### Nested Object Field Searching

Source: https://docs.jumpcloud.com/api/insights/directory/1.0/index.html

Demonstrates how to query fields within nested objects using dot notation.

```APIDOC
## Nested Object Event Data

To query fields within nested objects, use dot notation. Specify the parent field name followed by the child field name.

### Example Querying Nested Field `outer.eap_type`

```json
{
  "service": [
    "radius"
  ],
  "start_time": "2020-01-01T14:00:00Z",
  "search_term": {
    "and": [
      {
        "outer.eap_type": "PEAP"
      }
    ]
  }
}
```

This query returns events where the `outer` object has an `eap_type` value of `"PEAP"`.

**Note:** Dot notation can be used in `and/or` queries, field projection lists, and anywhere event fields can be specified.
```

--------------------------------

### Report Metadata Response Sample

Source: https://docs.jumpcloud.com/api/insights/directory/1.0/index.html

This JSON object represents the metadata returned when a report request is successfully submitted. It includes details about the report's status, creation, and artifacts.

```json
{
  "artifacts": [
    {
      "format": "CSV",
      "id": "string"
}
],
  "created_at": "string",
  "expiration": "string",
  "id": "string",
  "parameters": [
    {
    }
],
  "requester_email": "string",
  "requester_id": "string",
  "status": "PENDING",
  "type": "browser-patch-policy",
  "updated_at": "string"

}
```

--------------------------------

### Advanced Search: AND with List Values

Source: https://docs.jumpcloud.com/api/insights/directory/1.0/index.html

Use a list of values within the 'and' criteria to match events where a field matches any of the specified values.

```json
{
  "service": [
    "radius"
  ],
  "start_time": "2020-01-01T14:00:00Z",
  "search_term": {
    "and": [
      {
        "username": [
          "root",
          "admin"
        ]
      }
    ]
  }
}
```

--------------------------------

### Download a report

Source: https://docs.jumpcloud.com/api/insights/directory/1.0/index.html

Downloads a specific report artifact by its report ID and artifact ID. The report can be in CSV or JSON format.

```APIDOC
## GET /insights/directory/v1/reports/{report_id}/artifacts/{artifact_id}/content

### Description
Downloads a specific report artifact by its report ID and artifact ID. The report can be in CSV or JSON format.

### Method
GET

### Endpoint
https://api.jumpcloud.com/insights/directory/v1/reports/{report_id}/artifacts/{artifact_id}/content

### Parameters
#### Path Parameters
- **report_id** (string) - Required - Report ID
- **artifact_id** (string) - Required - Artifact ID

### Response
#### Success Response (200)
- **Report download in either CSV or JSON format**

#### Response Example
(No specific example provided in source, but would be the content of the report file)
```

--------------------------------

### Count Directory Events

Source: https://docs.jumpcloud.com/api/insights/directory/1.0/index.html

Counts directory events based on specified criteria. Allows filtering by service, time range, and specific fields. Supports sorting and full-text search.

```APIDOC
## POST /insights/directory/v1/events/count

### Description
Counts directory events based on specified criteria. Allows filtering by service, time range, and specific fields. Supports sorting and full-text search.

### Method
POST

### Endpoint
https://api.jumpcloud.com/insights/directory/v1/events/count

### Parameters
#### Request Body
- **service** (Array of strings) - Required - Service name to query. Enum: "alerts", "all", "directory", "ldap", "mdm", "notifications", "object_storage", "password_manager", "radius", "reports", "saas_app_management", "software", "sso", "systems", "access_management", "asset_management", "workflows", "genai", "aigw", "di_events"
- **start_time** (string <date-time>) - Required - Query start time, UTC in RFC3339 format
- **end_time** (string <date-time>) - Optional - Query end time, UTC in RFC3339 format
- **exact_match** (string) - Optional - For specifying exact match query, do not use with full text query
- **fields** (Array of strings) - Optional - List of fields to return from query
- **limit** (integer <int64>) - Optional - Max number of rows to return
- **q** (string) - Optional - For specifying a full text query
- **search_after** (Array of objects) - Optional - Specific query to search after, see x-* response headers for next values
- **search_term** (object) - Optional - SearchTerm is the filter portion of the query it contains only one of 'and', 'or', or 'not' conjunction maps
- **skip** (integer <int64>) - Optional - Offset into the result set to start with when returning
- **sort** (string) - Optional - ASC or DESC order for timestamp

### Request Example
```json
{
  "service": ["all"],
  "start_time": "2021-07-14T23:00:00Z",
  "end_time": "2021-07-28T14:00:00Z",
  "sort": "DESC",
  "fields": ["timestamp", "event_type", "initiated_by", "success", "client_ip", "provider", "organization"]
}
```

### Response
#### Success Response (200)
- **count** (integer) - Count of matching event rows

#### Response Example
```json
{
  "count": 0
}
```
```

--------------------------------

### Timestamp Comparisons (after)

Source: https://docs.jumpcloud.com/api/insights/directory/1.0/index.html

Use operators like 'after' for timestamp field comparisons.

```json
{
  "service": ["all"],
  "start_time": "2026-05-01T00:00:00Z",
  "search_term": {
    "and": [
      {
        "field": "timestamp",
        "operator": "after",
        "value": "2026-05-07T00:00:00Z"
      }
    ]
  }
}
```

--------------------------------

### JSON Event Interval Query Body Schema

Source: https://docs.jumpcloud.com/api/insights/directory/1.0/index.html

Defines the structure for querying event counts within specified intervals. Includes parameters for time range, services, and bucketing.

```json
{
  "end_time": "2019-08-24T14:15:22Z",
  "service": [
    "alerts"
  ],
  "start_time": "2019-08-24T14:15:22Z",
  "exact_match": "string",
  "interval_unit": "s",
  "interval_value": "string",
  "q": "string",
  "search_term": {
    "and": { },
    "not": { },
    "or": { }
  },
  "timezone": "string"
}
```