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, making it easier to audit, analyze usage, 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. File Reads - When Storage Connection files are read through Vendia MCP Server
5. File Writes - When Storage Connection files are written through Vendia MCP Server
6. File Deletes - When Storage Connection files are deleted through Vendia MCP Server

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
}