Read Receipts

Read Receipts is a Vendia feature that tracks and logs data access operations within a Uni. This feature provides visibility into who is accessing what data, when, and how, enabling better audit trails, usage analytics, and compliance monitoring.

How It Works

What Gets Tracked

Read 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. File Reads - When Storage Connection files are accessed through Vendia MCP Server

When Read Receipts Are Created

• GraphQL Operations: A read receipt is created for each GraphQL query or subscription
• SQL Operations: A read receipt is created for each SQL query execution
• File Reads: A read receipt is created for each Storage Connection file read operation through MCP
• Batching: Multiple receipts are batched together for processing efficiency

Timing and Frequency

• 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 Read 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 or FILE_READ

Timing and Status

• Read Time: Timestamp when the query was executed
• Status: Either SUCCESS or FAILED
• Error Message: Details if the query failed (truncated to 500 characters)

Accessing Read Receipts

Using the Vendia UI

Read Receipts are available through the Vendia web interface:

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

The Read Receipts interface allows you to:

• View all data access operations 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

Read 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, Read Receipts can be queried through the GraphQL API:

1. View Read 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
}