Linear Cost Tuning

Contents

• Overview
• Prerequisites
• Instructions
• Output
• Error Handling
• Examples
• Resources

Overview

Optimize Linear API usage to maximize efficiency and minimize costs through caching, batching, and smart query patterns.

Prerequisites

• Working Linear integration
• Monitoring in place
• Understanding of usage patterns

Cost Factors

Instructions

Step 1: Audit Current Usage

Track requests, complexity, and bytes transferred. Project monthly usage to identify optimization targets.

Step 2: Replace Polling with Webhooks

// BAD: Polling every minute
setInterval(async () => {
  const issues = await client.issues({ first: 100 });
  await syncIssues(issues.nodes);
}, 60000);  # 60000: 1 minute in ms

// GOOD: Use webhooks for real-time updates
app.post("/webhooks/linear", async (req, res) => {
  const event = req.body;
  await handleEvent(event);
  res.sendStatus(200);  # HTTP 200 OK
});

Step 3: Optimize Query Complexity

// BAD: ~500 complexity - deeply nested  # HTTP 500 Internal Server Error
const expensive = `query { issues(first: 50) { nodes { id title assignee { name } labels { nodes { name } } comments(first: 10) { nodes { body user { name } } } } } }`;

// GOOD: ~100 complexity - flat fields only
const cheap = `query { issues(first: 50) { nodes { id identifier title priority } } }`;

Step 4: Implement Request Coalescing and Caching

Deduplicate in-flight requests and cache responses with appropriate TTLs.

Step 5: Filter Webhook Events

Skip bot events, trivial updates, and irrelevant teams to reduce processing load.

See detailed implementation for full code examples of usage tracking, conditional fetching, coalescing, and lazy loading patterns.

Output

• Usage audit with projected monthly costs
• Polling replaced with webhooks
• Query complexity reduced
• Request coalescing and caching active

Error Handling

Examples

Cost Reduction Checklist

• Replace polling with webhooks
• Implement request caching (5-min TTL)
• Use request coalescing for concurrent calls
• Filter webhook events by team and field
• Minimize query complexity (<250 per query)
• Use lazy loading for static data (teams, states)

Resources

• Linear Rate Limiting
• Query Complexity Guide
• Webhook Best Practices

Next Steps

Learn production architecture with linear-reference-architecture.