Analytics Configuration

The configuration and schema endpoints let you discover what event types, fields, and limits your store supports. Use these endpoints to build dynamic event tracking that adapts automatically as new event types or fields become available.

Authentication

Header	Description
x-storeid	Your store identifier
x-storesecret	Read-only API secret

Get Analytics Configuration

Returns the supported event types, batch limits, and funnel stage definitions for your store.

curl -X GET "https://api.seekora.ai/analytics/config" \
  -H "x-storeid: your-store-id" \
  -H "x-storesecret: your-read-secret"

Example Response

{
  "event_types": ["search", "click", "conversion", "custom"],
  "batch_limits": {
    "max_events_per_batch": 100,
    "max_payload_size_bytes": 1048576
  },
  "funnel_stages": [
    { "name": "search", "order": 1 },
    { "name": "click", "order": 2 },
    { "name": "add_to_cart", "order": 3 },
    { "name": "conversion", "order": 4 }
  ],
  "retention_days": 90,
  "personalization_enabled": true
}

Response Fields

Field	Description
event_types	List of accepted event type values
batch_limits.max_events_per_batch	Maximum number of events in a single batch request
batch_limits.max_payload_size_bytes	Maximum request body size in bytes
funnel_stages	Ordered stages used for funnel analysis in the analytics dashboard
retention_days	How long event data is retained
personalization_enabled	Whether personalization features are active for your store

Get Analytics Schema

Returns the field definitions and validation rules for each event type. Use this to understand what fields are required, optional, or recommended for each event.

curl -X GET "https://api.seekora.ai/analytics/schema" \
  -H "x-storeid: your-store-id" \
  -H "x-storesecret: your-read-secret"

Example Response

{
  "event_types": {
    "search": {
      "fields": {
        "query": { "type": "string", "required": true },
        "total_results": { "type": "integer", "required": false },
        "page": { "type": "integer", "required": false },
        "filters_applied": { "type": "object", "required": false }
      }
    },
    "click": {
      "fields": {
        "query": { "type": "string", "required": false, "recommended": true },
        "document_id": { "type": "string", "required": true },
        "position": { "type": "integer", "required": false }
      }
    },
    "conversion": {
      "fields": {
        "query": { "type": "string", "required": false, "recommended": true },
        "document_id": { "type": "string", "required": true },
        "revenue": { "type": "float", "required": false },
        "currency": { "type": "string", "required": false },
        "order_id": { "type": "string", "required": false }
      }
    },
    "custom": {
      "fields": {
        "name": { "type": "string", "required": true },
        "document_id": { "type": "string", "required": false },
        "query": { "type": "string", "required": false },
        "metadata": { "type": "object", "required": false }
      }
    }
  }
}

Usage Patterns

Dynamic Event Validation

Fetch the schema at application startup and validate events client-side before sending them to the API. This reduces rejected events and avoids unnecessary network requests.

// Fetch schema once at startup
const response = await fetch('https://api.seekora.ai/analytics/schema', {
  headers: {
    'x-storeid': 'your-store-id',
    'x-storesecret': 'your-read-secret'
  }
});
const schema = await response.json();

// Validate an event against the schema
function validateEvent(eventType, data) {
  const eventSchema = schema.event_types[eventType];
  if (!eventSchema) return { valid: false, error: `Unknown event type: ${eventType}` };

  for (const [field, rules] of Object.entries(eventSchema.fields)) {
    if (rules.required && !(field in data)) {
      return { valid: false, error: `Missing required field: ${field}` };
    }
  }
  return { valid: true };
}

Respecting Batch Limits

Use the configuration endpoint to determine the maximum batch size instead of hardcoding it.

const config = await fetch('https://api.seekora.ai/analytics/config', {
  headers: {
    'x-storeid': 'your-store-id',
    'x-storesecret': 'your-read-secret'
  }
}).then(r => r.json());

const MAX_BATCH_SIZE = config.batch_limits.max_events_per_batch;

// Chunk events into batches that respect the limit
function chunkEvents(events) {
  const chunks = [];
  for (let i = 0; i < events.length; i += MAX_BATCH_SIZE) {
    chunks.push(events.slice(i, i + MAX_BATCH_SIZE));
  }
  return chunks;
}

Best Practices

• Cache configuration responses. These values change infrequently. Fetch them once at application startup or cache them for several hours.
• Use the schema endpoint for client-side validation. Catching invalid events before they are sent reduces error rates and improves data quality.
• Check funnel_stages for analytics dashboard alignment. Ensure your event tracking covers all defined funnel stages to get complete funnel visualizations.
• Monitor retention_days. If you need historical data beyond the retention window, export it to your own data warehouse before it expires.