# post\_\_systemevent

`POST /systemevent`

*Query System Events*

Query system events from the SystemEvent table with advanced filtering and pagination capabilities. This endpoint allows users to retrieve audit logs and system activity events based on various criteria including timestamps, context, event types, users, and workspaces.

**Key Features:**

* Advanced filtering by timestamp range, context, event type, user, and workspace
* Role-based access control (OWNER/ADMIN can query any user's events, regular users limited to their own)
* Pagination support with configurable skip and take parameters
* Default 24-hour time window when no timestamps are specified
* Context and event type translation from numeric indices to human-readable strings
* **Read/unread tracking**: Optional filter to return only unread events; each event includes a `showUnread` flag for the current user
* Comprehensive audit logging for security and compliance

**Authentication:**

* Requires valid Bearer token authentication
* User must be associated with an organization
* Role-based permissions determine data access scope

**Access Control:**

* **OWNER/ADMINISTRATORS**: Can query events for any user and workspace within their organization
* **Regular Users**: Limited to querying their own events and workspaces they belong to
* All users can only access events from their own organization

**Filtering Options:**

* **Timestamp Range**: Filter events by `from_timestamp` and `to_timestamp` (ISO 8601 format)
* **Context**: Filter by context type (workspace, bucket, repo, user, org, etc.)
* **Event Type**: Filter by event type (created, updated, deleted)
* **User**: Filter by specific user ID (role-dependent)
* **Workspace**: Filter by specific workspace ID (role-dependent)
* **Context ID**: Filter by specific context identifier
* **Show unread only**: When `showUnread` is `true`, only events that the current user has not read are returned (useful for notification badges and “unread” views)

**Pagination:**

* `skip`: Number of records to skip (default: 0, minimum: 0)
* `take`: Number of records to return (default: 20, minimum: 1, maximum: 100)

**Context Types:**

* `workspace` (0)
* `bucket` (1)
* `repo` (2)
* `user` (3)
* `org` (4)
* `workspaceuser` (5)
* `apikey` (6)
* `usersettings` (7)
* `orgsettings` (8)
* `flashbacknode` (9)
* `orgkey` (10)

**Event Types:**

* `created` (0)
* `updated` (1)
* `deleted` (2)

**Read/Unread behavior**

* **Request (`showUnread`)**: Optional boolean. When `true`, the API returns only events that the **current authenticated user** has not marked as read. When omitted or `false`, all events matching the other filters are returned (each event still includes a `showUnread` value).
* **Response (`showUnread` on each event)**: Every event in the response includes a `showUnread` boolean indicating whether the **current user** has read that event. `true` means the user has not read it (e.g. for highlighting in a notification list); `false` means they have. Read state is stored per user and per event on the server.
* To mark an event as read or unread, use [POST /systemevent/:id/read](/support-reference/platform-api-reference/other-apis/post__systemevent_read.md) and [DELETE /systemevent/:id/read](/support-reference/platform-api-reference/other-apis/delete__systemevent_read.md).

#### TypeScript Client Library

```typescript
public getSystemEvents = async (data: SystemEventQueryRequest): Promise<SystemEventQueryResponse> => {
  return this.makeRequest<SystemEventQueryResponse>('systemevent', 'POST', data);
};
```

#### Code Samples

{% tabs %}
{% tab title="Shell" %}

```shell
# Query system events for the last 24 hours
curl -X POST https://backend.flashback.tech/systemevent \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer your-jwt-token' \
  -d '{
    "skip": 0,
    "take": 20
  }'

# Query events for a specific time range and context
curl -X POST https://backend.flashback.tech/systemevent \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer your-jwt-token' \
  -d '{
    "from_timestamp": "2024-01-01T00:00:00.000Z",
    "to_timestamp": "2024-01-31T23:59:59.999Z",
    "context": 0,
    "event": 0,
    "skip": 0,
    "take": 50
  }'
```

{% endtab %}

{% tab title="HTTP" %}

```http
POST https://backend.flashback.tech/systemevent HTTP/1.1
Host: backend.flashback.tech
Content-Type: application/json
Accept: application/json
Authorization: Bearer your-jwt-token

{
  "from_timestamp": "2024-01-01T00:00:00.000Z",
  "to_timestamp": "2024-01-31T23:59:59.999Z",
  "contextId": "workspace-123",
  "context": 0,
  "event": 0,
  "userId": "user-456",
  "workspaceId": "workspace-789",
  "showUnread": false,
  "skip": 0,
  "take": 20
}
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const inputBody = {
  "from_timestamp": "2024-01-01T00:00:00.000Z",
  "to_timestamp": "2024-01-31T23:59:59.999Z",
  "contextId": "workspace-123",
  "context": 0,
  "event": 0,
  "userId": "user-456",
  "workspaceId": "workspace-789",
  "showUnread": false,
  "skip": 0,
  "take": 20
};

const headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer your-jwt-token'
};

fetch('https://backend.flashback.tech/systemevent', {
  method: 'POST',
  body: JSON.stringify(inputBody),
  headers: headers
})
.then(function(res) {
  return res.json();
}).then(function(body) {
  console.log(body);
});
```

{% endtab %}

{% tab title="Ruby" %}

```ruby
require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer your-jwt-token'
}

body = {
  'from_timestamp' => '2024-01-01T00:00:00.000Z',
  'to_timestamp' => '2024-01-31T23:59:59.999Z',
  'contextId' => 'workspace-123',
  'context' => 0,
  'event' => 0,
  'userId' => 'user-456',
  'workspaceId' => 'workspace-789',
  'showUnread' => false,
  'skip' => 0,
  'take' => 20
}

result = RestClient.post 'https://backend.flashback.tech/systemevent',
  body.to_json, headers: headers

p JSON.parse(result)
```

{% endtab %}

{% tab title="Python" %}

```python
import requests
import json

headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer your-jwt-token'
}

body = {
  'from_timestamp': '2024-01-01T00:00:00.000Z',
  'to_timestamp': '2024-01-31T23:59:59.999Z',
  'contextId': 'workspace-123',
  'context': 0,
  'event': 0,
  'userId': 'user-456',
  'workspaceId': 'workspace-789',
  'showUnread': False,
  'skip': 0,
  'take': 20
}

r = requests.post('https://backend.flashback.tech/systemevent', 
                  headers=headers, 
                  data=json.dumps(body))

print(r.json())
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'Authorization' => 'Bearer your-jwt-token',
);

$body = array(
    'from_timestamp' => '2024-01-01T00:00:00.000Z',
    'to_timestamp' => '2024-01-31T23:59:59.999Z',
    'contextId' => 'workspace-123',
    'context' => 0,
    'event' => 0,
    'userId' => 'user-456',
    'workspaceId' => 'workspace-789',
    'showUnread' => false,
    'skip' => 0,
    'take' => 20
);

$client = new \GuzzleHttp\Client();

try {
    $response = $client->request('POST','https://backend.flashback.tech/systemevent', array(
        'headers' => $headers,
        'json' => $body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...
```

{% endtab %}

{% tab title="Java" %}

```java
URL obj = new URL("https://backend.flashback.tech/systemevent");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/json");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("Authorization", "Bearer your-jwt-token");

String jsonInputString = "{\"from_timestamp\":\"2024-01-01T00:00:00.000Z\",\"to_timestamp\":\"2024-01-31T23:59:59.999Z\",\"contextId\":\"workspace-123\",\"context\":0,\"event\":0,\"userId\":\"user-456\",\"workspaceId\":\"workspace-789\",\"showUnread\":false,\"skip\":0,\"take\":20}";

con.setDoOutput(true);
try(OutputStream os = con.getOutputStream()) {
    byte[] input = jsonInputString.getBytes("utf-8");
    os.write(input, 0, input.length);
}

int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());
```

{% endtab %}

{% tab title="Go" %}

```go
package main

import (
       "bytes"
       "net/http"
       "encoding/json"
)

func main() {
    body := map[string]interface{}{
        "from_timestamp": "2024-01-01T00:00:00.000Z",
        "to_timestamp": "2024-01-31T23:59:59.999Z",
        "contextId": "workspace-123",
        "context": 0,
        "event": 0,
        "userId": "user-456",
        "workspaceId": "workspace-789",
        "showUnread": false,
        "skip": 0,
        "take": 20,
    }

    jsonData, _ := json.Marshal(body)

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer your-jwt-token"},
    }

    data := bytes.NewBuffer(jsonData)
    req, err := http.NewRequest("POST", "https://backend.flashback.tech/systemevent", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}
```

{% endtab %}
{% endtabs %}

> Body parameter

```json
{
  "from_timestamp": "2024-01-01T00:00:00.000Z",
  "to_timestamp": "2024-01-31T23:59:59.999Z",
  "contextId": "workspace-123",
  "context": 0,
  "event": 0,
  "userId": "user-456",
  "workspaceId": "workspace-789",
  "showUnread": false,
  "skip": 0,
  "take": 20
}
```

#### Parameters <a href="#post__systemevent-parameters" id="post__systemevent-parameters"></a>

| Name              | In   | Type    | Required | Description                                                   |
| ----------------- | ---- | ------- | -------- | ------------------------------------------------------------- |
| body              | body | object  | true     | System event query parameters                                 |
| » from\_timestamp | body | string  | false    | Start timestamp for filtering events (ISO 8601 format)        |
| » to\_timestamp   | body | string  | false    | End timestamp for filtering events (ISO 8601 format)          |
| » contextId       | body | string  | false    | Specific context identifier to filter by                      |
| » context         | body | number  | false    | Context type index (0-10)                                     |
| » event           | body | number  | false    | Event type index (0-2)                                        |
| » userId          | body | string  | false    | User ID to filter by (role-dependent access)                  |
| » workspaceId     | body | string  | false    | Workspace ID to filter by (role-dependent access)             |
| » showUnread      | body | boolean | false    | When `true`, only return events the current user has not read |
| » skip            | body | number  | true     | Number of records to skip (minimum: 0)                        |
| » take            | body | number  | true     | Number of records to return (minimum: 1, maximum: 100)        |

**Context Type Values**

| Index | Context Type  | Description                  |
| ----- | ------------- | ---------------------------- |
| 0     | workspace     | Workspace-related events     |
| 1     | bucket        | Bucket-related events        |
| 2     | repo          | Repository-related events    |
| 3     | user          | User-related events          |
| 4     | org           | Organization-related events  |
| 5     | workspaceuser | Workspace user events        |
| 6     | apikey        | API key events               |
| 7     | usersettings  | User settings events         |
| 8     | orgsettings   | Organization settings events |
| 9     | flashbacknode | Flashback node events        |
| 10    | orgkey        | Organization key events      |

**Event Type Values**

| Index | Event Type | Description      |
| ----- | ---------- | ---------------- |
| 0     | created    | Resource created |
| 1     | updated    | Resource updated |
| 2     | deleted    | Resource deleted |

> Example responses

> 200 Response

```json
{
  "events": [
    {
      "id": 12345,
      "timestamp": "2024-01-15T10:30:00.000Z",
      "contextId": "workspace-123",
      "context": "workspace",
      "event": "created",
      "orgId": "org-456",
      "userId": "user-789",
      "userName": "Jane Doe",
      "userEmail": "jane@example.com",
      "workspaceId": "workspace-123",
      "jsonData": "{\"name\":\"My Workspace\",\"description\":\"A new workspace\"}",
      "showUnread": true
    },
    {
      "id": 12344,
      "timestamp": "2024-01-15T10:25:00.000Z",
      "contextId": "bucket-456",
      "context": "bucket",
      "event": "updated",
      "orgId": "org-456",
      "userId": "user-789",
      "userName": "Jane Doe",
      "userEmail": "jane@example.com",
      "workspaceId": "workspace-123",
      "jsonData": "{\"name\":\"Updated Bucket\",\"region\":\"us-east-1\"}",
      "showUnread": false
    }
  ],
  "total": 150,
  "skip": 0,
  "take": 20
}
```

> 400 Response

```json
{
  "error": "skip must be >= 0"
}
```

> 401 Response

```json
{
  "error": "Unauthorized"
}
```

> 403 Response

```json
{
  "error": "Insufficient permissions to query other users' events"
}
```

> 500 Response

```json
{
  "error": "Internal server error"
}
```

#### Responses <a href="#post__systemevent-responses" id="post__systemevent-responses"></a>

| Status | Meaning                                                                    | Description                                 | Schema |
| ------ | -------------------------------------------------------------------------- | ------------------------------------------- | ------ |
| 200    | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)                    | System events retrieved successfully        | Inline |
| 400    | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)           | Validation error or invalid parameters      | Inline |
| 401    | [Unauthorized](https://tools.ietf.org/html/rfc7231#section-6.5.2)          | Authentication required or user not found   | Inline |
| 403    | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3)             | Insufficient permissions for requested data | Inline |
| 500    | [Internal Server Error](https://tools.ietf.org/html/rfc7231#section-6.6.1) | Internal server error                       | Inline |

#### Response Schema <a href="#post__systemevent-responseschema" id="post__systemevent-responseschema"></a>

Status Code **200**

| Name           | Type    | Required | Restrictions | Description                                                                           |
| -------------- | ------- | -------- | ------------ | ------------------------------------------------------------------------------------- |
| » events       | array   | true     | none         | Array of system events                                                                |
| »» id          | number  | true     | none         | Unique event identifier                                                               |
| »» timestamp   | string  | true     | none         | Event timestamp in ISO 8601 format                                                    |
| »» contextId   | string  | true     | none         | Context identifier                                                                    |
| »» context     | string  | true     | none         | Human-readable context type                                                           |
| »» event       | string  | true     | none         | Human-readable event type                                                             |
| »» orgId       | string  | true     | none         | Organization ID                                                                       |
| »» userId      | string  | true     | none         | User ID who triggered the event                                                       |
| »» userName    | string  | true     | none         | Display name of the user who triggered the event                                      |
| »» userEmail   | string  | true     | none         | Email of the user who triggered the event                                             |
| »» workspaceId | string  | false    | none         | Workspace ID (null if not applicable)                                                 |
| »» jsonData    | string  | false    | none         | Additional event data in JSON format                                                  |
| »» showUnread  | boolean | true     | none         | Whether the **current user** has not read this event; `true` = unread, `false` = read |
| » total        | number  | true     | none         | Total number of events matching the query                                             |
| » skip         | number  | true     | none         | Number of records skipped                                                             |
| » take         | number  | true     | none         | Number of records returned                                                            |

Status Code **400**

| Name    | Type   | Required | Restrictions | Description                                   |
| ------- | ------ | -------- | ------------ | --------------------------------------------- |
| » error | string | true     | none         | Error message describing the validation issue |

Status Code **401**

| Name    | Type   | Required | Restrictions | Description                                     |
| ------- | ------ | -------- | ------------ | ----------------------------------------------- |
| » error | string | true     | none         | Error message indicating authentication failure |

Status Code **403**

| Name    | Type   | Required | Restrictions | Description                                       |
| ------- | ------ | -------- | ------------ | ------------------------------------------------- |
| » error | string | true     | none         | Error message indicating insufficient permissions |

Status Code **500**

| Name    | Type   | Required | Restrictions | Description                                 |
| ------- | ------ | -------- | ------------ | ------------------------------------------- |
| » error | string | true     | none         | Error message describing the internal error |

This operation requires authentication via Bearer token and enforces role-based access control for data security.


---

# 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://docs.flashback.tech/support-reference/platform-api-reference/other-apis/post__systemevent.md?ask=<question>
```

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.