Imported from jeremylongshore/tons-of-skills-marketplace (skills/.curated/attio-cost-tuning/SKILL.md). Install upstream with npx skills add jeremylongshore/tons-of-skills-marketplace --skill attio-cost-tuning. Copyright stays with the author (MIT).

Attio Cost Tuning

Overview

Attio pricing is based on workspace seats, not API calls. However, API rate limits effectively cap throughput, so optimizing request volume improves both performance and cost efficiency. This skill covers practical strategies to reduce unnecessary API calls.

Attio Pricing Model

API access requires Plus plan or higher. Rate limits are per-workspace, not per-seat.

Instructions

Step 1: Audit Current API Usage

// Instrument all API calls to measure usage patterns
class AttioUsageTracker {
  private calls: Array<{
    method: string;
    path: string;
    timestamp: number;
    durationMs: number;
    cached: boolean;
  }> = [];

  async track<T>(
    method: string,
    path: string,
    operation: () => Promise<T>,
    cached = false
  ): Promise<T> {
    const start = Date.now();
    try {
      const result = await operation();
      this.calls.push({
        method, path, timestamp: start,
        durationMs: Date.now() - start, cached,
      });
      return result;
    } catch (err) {
      this.calls.push({
        method, path, timestamp: start,
        durationMs: Date.now() - start, cached: false,
      });
      throw err;
    }
  }

  report(windowMs = 3600_000): {
    totalCalls: number;
    cachedCalls: number;
    topEndpoints: Array<{ path: string; count: number }>;
  } {
    const cutoff = Date.now() - windowMs;
    const recent = this.calls.filter((c) => c.timestamp > cutoff);
    const cached = recent.filter((c) => c.cached).length;

    const endpointCounts = new Map<string, number>();
    for (const call of recent) {
      const key = `${call.method} ${call.path}`;
      endpointCounts.set(key, (endpointCounts.get(key) || 0) + 1);
    }

    const topEndpoints = [...endpointCounts.entries()]
      .sort((a, b) => b[1] - a[1])
      .slice(0, 10)
      .map(([path, count]) => ({ path, count }));

    return { totalCalls: recent.length, cachedCalls: cached, topEndpoints };
  }
}

Step 2: Reduce Request Volume

The five biggest cost/rate-limit savers:

Step 3: Eliminate Polling with Webhooks

// BAD: Polling every 30 seconds for changes
setInterval(async () => {
  const records = await client.post("/objects/people/records/query", {
    filter: { updated_at: { $gt: lastCheck.toISOString() } },
    limit: 500,
  });
  for (const record of records.data) await processUpdate(record);
  lastCheck = new Date();
}, 30_000);
// Cost: 2,880 requests/day MINIMUM (even with no changes)

// GOOD: Webhook-driven (0 requests when no changes)
app.post("/webhooks/attio", async (req, res) => {
  res.status(200).json({ received: true });
  const event = req.body;
  if (event.event_type === "record.updated") {
    const record = await client.get(
      `/objects/${event.object.api_slug}/records/${event.record.id.record_id}`
    );
    await processUpdate(record);
  }
});
// Cost: 1 request per actual change

Step 4: Smart Caching Tiers

import { LRUCache } from "lru-cache";

// Tier 1: Schema data (changes very rarely)
const schemaCache = new LRUCache<string, unknown>({
  max: 100,
  ttl: 30 * 60 * 1000, // 30 minutes
});

// Tier 2: Record data (changes occasionally)
const recordCache = new LRUCache<string, unknown>({
  max: 5000,
  ttl: 5 * 60 * 1000, // 5 minutes
});

// Tier 3: List/query results (changes frequently)
const queryCache = new LRUCache<string, unknown>({
  max: 200,
  ttl: 30 * 1000, // 30 seconds
});

function getCacheForPath(path: string): LRUCache<string, unknown> {
  if (path.includes("/attributes") || path === "/objects") return schemaCache;
  if (path.includes("/records/") && !path.includes("/query")) return recordCache;
  return queryCache;
}

Step 5: Request Budget Monitor

class AttioRequestBudget {
  private requestsToday = 0;
  private dayStart = this.todayStart();
  private readonly dailyBudget: number;
  private readonly warningThreshold: number;

  constructor(dailyBudget = 10_000) {
    this.dailyBudget = dailyBudget;
    this.warningThreshold = dailyBudget * 0.8;
  }

  private todayStart(): number {
    const d = new Date();
    d.setHours(0, 0, 0, 0);
    return d.getTime();
  }

  recordRequest(): void {
    const today = this.todayStart();
    if (today !== this.dayStart) {
      this.dayStart = today;
      this.requestsToday = 0;
    }
    this.requestsToday++;

    if (this.requestsToday === Math.floor(this.warningThreshold)) {
      console.warn(`Attio budget warning: ${this.requestsToday}/${this.dailyBudget} requests today`);
    }

    if (this.requestsToday >= this.dailyBudget) {
      console.error(`Attio daily budget exceeded: ${this.requestsToday} requests`);
    }
  }

  getUsage(): { today: number; budget: number; percentUsed: number } {
    return {
      today: this.requestsToday,
      budget: this.dailyBudget,
      percentUsed: Math.round((this.requestsToday / this.dailyBudget) * 100),
    };
  }
}

Step 6: SQL Usage Dashboard

If you log API calls to a database:

-- Daily request volume (last 30 days)
SELECT
  DATE(timestamp) AS day,
  COUNT(*) AS total_requests,
  COUNT(CASE WHEN cached THEN 1 END) AS cache_hits,
  ROUND(COUNT(CASE WHEN cached THEN 1 END) * 100.0 / COUNT(*), 1) AS cache_hit_pct,
  ROUND(AVG(duration_ms), 0) AS avg_latency_ms
FROM attio_api_log
WHERE timestamp >= CURRENT_DATE - INTERVAL '30 days'
GROUP BY DATE(timestamp)
ORDER BY day DESC;

-- Top endpoints by volume (identify optimization targets)
SELECT
  method || ' ' || path AS endpoint,
  COUNT(*) AS calls,
  ROUND(AVG(duration_ms), 0) AS avg_ms,
  COUNT(CASE WHEN status = 429 THEN 1 END) AS rate_limited
FROM attio_api_log
WHERE timestamp >= CURRENT_DATE - INTERVAL '7 days'
GROUP BY method, path
ORDER BY calls DESC
LIMIT 10;

Cost Optimization Checklist

[ ] Object schema calls cached (30-minute TTL)
[ ] Record lookups cached (5-minute TTL with webhook invalidation)
[ ] Polling replaced with webhooks where possible
[ ] Bulk operations use $in filter (1 request instead of N)
[ ] Pagination uses limit: 500 (max page size)
[ ] Unnecessary API calls identified and eliminated
[ ] Usage monitoring in place with daily budget alerts
[ ] Cache hit rate > 50% on read-heavy workloads

Prerequisites

Confirm that you have an Attio workspace appropriate to the task, a dedicated non-production record or workspace for testing, and only the API token scopes or administrative access required by the procedure.

Output

Following this guide produces the Attio integration outcome for its topic—configuration, validation evidence, operational recovery, or a documented migration result. Record command output and relevant identifiers so a failed step is traceable.

Examples

Start with the smallest applicable command or code example in the relevant section, using a dedicated test record or workspace and non-production credentials. Confirm the expected response or validation result before applying the pattern to production.

Error Handling

Resources

• Attio Pricing
• Attio Rate Limiting
• Attio Webhooks Guide

Next Steps

For architecture patterns, see attio-reference-architecture.