---

name: klaviyo-performance-tuning description: | Optimize Klaviyo API performance with caching, batching, and pagination tuning. Use when experiencing slow API responses, implementing caching strategies, or optimizing request throughput for Klaviyo integrations. Trigger with phrases like "klaviyo performance", "optimize klaviyo", "klaviyo latency", "klaviyo caching", "klaviyo slow", "klaviyo batch". allowed-tools: Read, Write, Edit version: 1.7.0 license: MIT author: Jeremy Longshore jeremy@intentsolutions.io tags:

• saas
• klaviyo
• email-marketing
• cdp compatibility: Designed for Claude Code

---

Klaviyo Performance Tuning

Overview

Optimize Klaviyo API performance with response caching, request batching, cursor-based pagination, sparse fieldsets, and connection pooling. This skill diagnoses where an integration is slow, then applies the right technique — payload reduction, memory caching, bounded pagination, request coalescing, or rate-limit-aware concurrency.

Read this file for the workflow and the decision guide. Full, copy-pasteable code for every step lives in references/implementation.md; combined real-world scenarios live in references/examples.md.

Prerequisites

• klaviyo-api SDK installed
• Understanding of Klaviyo's rate limits (75 req/s burst, 700 req/min)
• Redis or in-memory cache (optional)
• For batching/concurrency helpers: dataloader, p-queue, lru-cache

Klaviyo API Performance Characteristics

Operation	Typical Latency	Max Page Size
Get Profile by ID	50-150ms	N/A
Get Profiles (list)	100-300ms	20 (default), 100 (some endpoints)
Create Profile	100-200ms	N/A
Create Event	50-100ms	N/A
Get Segment Profiles	200-500ms	20
Campaign Operations	200-500ms	20

Instructions

Apply the techniques in order — each is independent, so start with the one that matches your bottleneck. Every step below has a full implementation in references/implementation.md.

Step 1: Sparse Fieldsets (Reduce Payload Size)

Klaviyo supports JSON:API sparse fieldsets — request only the fields you need instead of the 20+ default attributes. This is the cheapest win and applies to every read.

// GOOD: Only fetch the fields you use (much smaller payload)
const profiles = await profilesApi.getProfiles({
  fieldsProfile: ['email', 'first_name', 'created'],  // snake_case = API names
});

Step 2: Response Caching

Wrap read calls in an LRUCache keyed by query, with per-resource TTLs (profiles 5 min, segments 15 min — they change less often). See the caching implementation in references/implementation.md.

Step 3: Efficient Pagination

Use a fetchAllPages helper that follows the links.next cursor with a maxPages ceiling so large exports terminate predictably. See the pagination implementation in references/implementation.md.

Step 4: Request Batching with DataLoader

Coalesce many getProfile(id) calls in a single tick into concurrency-controlled requests with DataLoader (maxBatchSize: 10, 50 ms window). See the batching implementation in references/implementation.md.

Step 5: Parallel API Calls with Concurrency Control

Drive bulk writes through a PQueue capped at 50 req/s — a safe margin under the 75 req/s burst limit — with progress logging. See the concurrency implementation in references/implementation.md.

Step 6: Performance Monitoring

Wrap calls in measuredCall and read a p95 summary via getPerfSummary to find the real bottleneck before optimizing. See the monitoring implementation in references/implementation.md.

Output

Applying this skill produces:

• Sparse-fieldset read calls with 50-80% smaller payloads on list endpoints.
• A cache module (src/klaviyo/cache.ts) that serves repeated reads from memory with per-resource TTLs.
• A pagination helper (src/klaviyo/pagination.ts) that safely walks cursor-paginated endpoints to completion under a maxPages guard.
• Batching + concurrency helpers that keep bulk operations under Klaviyo's 75 req/s burst and 700 req/min ceilings.
• A perf-monitoring module (src/klaviyo/perf-monitor.ts) emitting per-operation avg, p95, and count so you can verify the gains.

Error Handling

Issue	Cause	Solution
Cache stampede	Many requests on cache miss	Use stale-while-revalidate pattern
Pagination timeout	Very large datasets	Set maxPages limit, process in chunks
Rate limit on bulk ops	Too much concurrency	Reduce PQueue concurrency/intervalCap
Slow filter queries	Complex filter expressions	Simplify filters, use segment IDs instead

Examples

Worked, end-to-end scenarios that combine the steps above are in references/examples.md:

• Fast cached profile lookup — sparse fieldsets + LRU caching for a repeated lookup.
• Export a large list — bounded cursor pagination for a multi-hundred-thousand-member list.
• Bulk-update 10,000 profiles — PQueue concurrency under the rate limit.
• Measure where the time goes — measuredCall + getPerfSummary to find the slow op first.

Minimal caching example (full versions in the reference):

import { cachedKlaviyoCall } from './cache';

const profile = await cachedKlaviyoCall(
  `profile:${email}`,
  () => profilesApi.getProfiles({ filter: `equals(email,"${email}")` }),
  5 * 60 * 1000  // 5 minute TTL
);

Resources

• Klaviyo API Filtering
• JSON:API Sparse Fieldsets
• DataLoader
• p-queue
• references/implementation.md — full code for every step
• references/examples.md — combined real-world scenarios

Next Steps

Once reads are cached and bulk writes are rate-limit-safe, profile the workload with getPerfSummary (Step 6) to confirm the p95 improvement, then tune TTLs and concurrency to your traffic. For cost optimization of the same integration, see the klaviyo-cost-tuning skill.