# Receipts

Receipts is a Vendia feature that captures and records reads, writes, and queries in a **workspace**. By covering GraphQL, SQL, and MCP server interactions, Receipts give you insight into who is interacting with data, when, and in what way. Receipts are automatically generated for all interactions, providing visibility into who is accessing or modifying data. This makes it easier to audit activity, analyze usage patterns, and ensure compliance.

## How It Works

### What Gets Tracked

Receipts are created for the following types of operations:

01. **GraphQL Queries** \- All GraphQL query operations  
02. **GraphQL Subscriptions** \- When subscriptions are established  
03. **SQL Queries** \- Iceberg SQL queries executed against the data  
04. **API Reads** \- When API GET requests are made through Vendia MCP Gateway API Connections  
05. **API Writes** \- When API POST, PUT, or DELETE requests are made through Vendia MCP Gateway API Connections  
06. **Storage Connection List** \- When Storage Connections are listed through Vendia MCP Gateway  
07. **Storage Connection Read** \- When Storage Connection metadata is read through Vendia MCP Gateway  
08. **File Reads** \- When Storage Connection files are read through Vendia MCP Gateway  
09. **File Creates** \- When Storage Connection files are created through Vendia MCP Gateway  
10. **File Writes** \- When Storage Connection files are written through Vendia MCP Gateway  
11. **File Deletes** \- When Storage Connection files are deleted through Vendia MCP Gateway

### Timing and Frequency

Receipts are created in batches for efficiency, while preserving and guaranteeing their correct chronological order.

- **Default Batch Window**: 5 minutes (300 seconds)  
- **Default Batch Size**: 25 receipts per batch  
- **Maximum Batch Size**: 100 receipts per batch  
- **Maximum Wait Time**: 5 minutes (300 seconds)

**Note:** These settings can be customized by contacting Vendia Support.

## Information Captured

Each Receipt contains the following information:

### Actor Information

- **Actor ID**: Unique identifier of the user/service making the request  
- **Actor Type**: One of:
  - **`VENDIA_USER`** \- Requests from Vendia platform users _(most common)_  
  - **`API_CREDENTIALS`** \- Requests using API credentials _(most common)_  
  - `API_KEY` \- Requests using API keys  
  - `JWT_EXTERNAL` \- External requests using JWT tokens  
  - `SMART_CONTRACT` \- Requests from smart contracts  
- **Role Information**(if applicable):
  - Role ID  
  - Role Name  
  - Role Version

### Request Context

- **Client Type**: How the request was made:
  - `VENDIA_UI` \- Through the Vendia web interface  
  - `MCP` \- Through Vendia’s MCP (Model Context Protocol) Server  
  - `OTHER` \- Other client types  
- **Client ID**: Specific client identifier (if available)  
- **Organization ID**: The organization that owns the data

### Query Details

- **Query**: The actual query text (GraphQL or SQL)  
- **Query Variables**: Variables passed with GraphQL queries (as JSON string)  
- **Query Type**: `GRAPHQL`, `ICEBERG_SQL`, `FILE_READ`, `FILE_CREATE`, `FILE_WRITE` and `FILE_DELETE`

### Timing and Status

- **Operation Time**: Timestamp when the operation was executed  
- **Status**: Either `SUCCESS` or `FAILED`  
- **Error Message**: Details if the query failed (truncated to 500 characters)

## Accessing Receipts

### Using the Vendia UI

Receipts are available through the Vendia web interface:

1. **Navigate to the Observe Page**: From your **workspace** dashboard, click on the “Observe” tab  
2. **Select Receipts**: Look for the “Receipts” tab within the Observe page  
3. **View and Filter**: Browse through the receipts with built-in filtering and sorting options

The Receipts interface allows you to:

- View receipts in chronological order  
- Filter by user, time range, query type, or query content  
- Sort results by most recent activity  
- Export data for compliance reporting

### System Operations

Receipts are **not** created for:

- System operations (actor type `VENDIA_SYSTEM`)  
- Internal maintenance operations

## Use Cases

### Audit and Compliance

- Track who accessed sensitive data  
- Maintain audit trails for regulatory compliance  
- Monitor data access patterns

### Usage Analytics

- Understand which data is most frequently accessed  
- Identify performance bottlenecks  
- Optimize data organization based on access patterns

### Security Monitoring

- Detect unusual access patterns  
- Monitor for potential data exfiltration  
- Track access by external users vs internal users

## Limitations

- Query text is limited (may be truncated for very large queries)  
- Error messages are truncated to 500 characters  
- Batch processing may introduce slight delays in receipt availability

## Advanced Usage

### GraphQL API Access

For programmatic access, Receipts can be queried through the GraphQL API:

1. **View Receipts**: Query the `listVendia_ReadReceiptItems` endpoint  
2. **Filter Results**: Filter by actor, time range, query content, etc.  
3. **Sort Results**: Sort by most recent first using `_vendia_updated_at`

### Example GraphQL Query

```
query ListReadReceipts(

$limit: Int

$nextToken: String

$filter: Vendia_ReadReceipt_FilterInput_ = {}

) {

listVendia_ReadReceiptItems(

order: { _vendia_updated_at: DESC }

limit: $limit

nextToken: $nextToken

filter: $filter

) {

Vendia_ReadReceiptItems {

_id

_owner

receipts {

actor {

id

type

roleId

roleName

roleVersion

}

clientType

clientId

readTime

orgId

query

queryVariables

queryType

fileKey

fileSourceId

fileSourceType

fileSourceName

status

errorMessage

}

}

nextToken

}

}
```

### Example Filters

```javascript
// Filter by specific actor ID

{

"filter": {

"_receiptsItem": {

"actor": {

"id": {

"eq": "user123"

}

}

}

},

"limit": 10

}

// Filter by query content

{

"filter": {

"_receiptsItem": {

"query": {

"contains": "Block"

}

}

},

"limit": 10

}
```