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:

1. GraphQL Queries - All GraphQL query operations
2. GraphQL Subscriptions - When subscriptions are established
3. SQL Queries - Iceberg SQL queries executed against the data
4. API Reads - When API GET requests are made through Vendia MCP Gateway API Connections
5. API Writes - When API POST, PUT, or DELETE requests are made through Vendia MCP Gateway API Connections
6. Storage Connection List - When Storage Connections are listed through Vendia MCP Gateway
7. Storage Connection Read - When Storage Connection metadata is read through Vendia MCP Gateway
8. File Reads - When Storage Connection files are read through Vendia MCP Gateway
9. 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

// Filter by specific actor ID

{

"filter": {

"_receiptsItem": {

"actor": {

"id": {

"eq": "user123"

}

}

}

},

"limit": 10

}

// Filter by query content

{

"filter": {

"_receiptsItem": {

"query": {

"contains": "Block"

}

}

},

"limit": 10

}