@channel47/linkedin-ads-mcp 0.1.0

package/server/index.js

@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  GetPromptRequestSchema,
+  ListPromptsRequestSchema,
+  ListResourcesRequestSchema,
+  ListToolsRequestSchema,
+  ReadResourceRequestSchema
+} from '@modelcontextprotocol/sdk/types.js';
+
+import { validateEnvironment } from './auth.js';
+import { listAccounts } from './tools/list-accounts.js';
+import { query } from './tools/query.js';
+import { analytics } from './tools/analytics.js';
+import { mutate } from './tools/mutate.js';
+import { getPromptsList, renderPrompt } from './prompts/templates.js';
+import { getResourcesList, readResource } from './resources/index.js';
+
+const SERVER_NAME = 'linkedin-ads-mcp';
+const SERVER_VERSION = '0.1.0';
+const READ_ONLY = process.env.LINKEDIN_ADS_READ_ONLY === 'true';
+
+const ALL_TOOLS = [
+  {
+    name: 'list_accounts',
+    description: 'List all accessible LinkedIn ad accounts for the authenticated token, with optional status/type filters.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        status: {
+          anyOf: [
+            { type: 'string' },
+            {
+              type: 'array',
+              items: { type: 'string' }
+            }
+          ],
+          description: 'Optional account status filter (ACTIVE, CANCELED, DRAFT, PENDING_DELETION, REMOVED). String or array.'
+        },
+        type: {
+          anyOf: [
+            { type: 'string' },
+            {
+              type: 'array',
+              items: { type: 'string' }
+            }
+          ],
+          description: 'Optional account type filter (BUSINESS, ENTERPRISE). String or array.'
+        },
+        limit: {
+          type: 'integer',
+          minimum: 1,
+          description: 'Maximum accounts to return (default: 1000)'
+        }
+      }
+    }
+  },
+  {
+    name: 'query',
+    description: 'Query campaigns, campaign groups, or creatives for a LinkedIn ad account. Supports either the numeric account ID or the urn:li:sponsoredAccount URN.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        account_id: {
+          type: 'string',
+          description: 'LinkedIn ad account ID. Supports either 123... or urn:li:sponsoredAccount:123...'
+        },
+        entity: {
+          type: 'string',
+          enum: ['campaigns', 'campaign_groups', 'creatives'],
+          description: 'Entity type to query'
+        },
+        status: {
+          anyOf: [
+            { type: 'string' },
+            {
+              type: 'array',
+              items: { type: 'string' }
+            }
+          ],
+          description: 'Optional status filter (e.g. ACTIVE, PAUSED, DRAFT, ARCHIVED). For creatives this filters intendedStatus.'
+        },
+        campaign_ids: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Creatives only: restrict to these campaign IDs (plain IDs or URNs)'
+        },
+        limit: {
+          type: 'integer',
+          minimum: 1,
+          description: 'Maximum rows to return (default: 100)'
+        }
+      },
+      required: ['entity']
+    }
+  },
+  {
+    name: 'analytics',
+    description: 'Fetch adAnalytics metrics pivoted by ACCOUNT, CAMPAIGN_GROUP, CAMPAIGN, or CREATIVE over a date range. Defaults to impressions, clicks, costInLocalCurrency, externalWebsiteConversions plus dateRange/pivotValues; at most 20 metric fields per call. No pagination (LinkedIn caps responses at 15,000 elements).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        account_id: {
+          type: 'string',
+          description: 'LinkedIn ad account ID used when entity_ids is omitted. Supports either 123... or urn:li:sponsoredAccount:123...'
+        },
+        pivot: {
+          type: 'string',
+          enum: ['ACCOUNT', 'CAMPAIGN_GROUP', 'CAMPAIGN', 'CREATIVE'],
+          description: 'Dimension to group results by'
+        },
+        start: {
+          type: 'string',
+          description: 'Start date (YYYY-MM-DD)'
+        },
+        end: {
+          type: 'string',
+          description: 'End date (YYYY-MM-DD). Omit for "through today".'
+        },
+        time_granularity: {
+          type: 'string',
+          enum: ['ALL', 'DAILY', 'MONTHLY'],
+          description: 'Time breakdown (default: ALL)'
+        },
+        entity_type: {
+          type: 'string',
+          enum: ['account', 'campaign_group', 'campaign', 'creative'],
+          description: 'Entity type of entity_ids (default: account)'
+        },
+        entity_ids: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Plain IDs (or URNs) to scope the report to. Defaults to the account when omitted.'
+        },
+        fields: {
+          anyOf: [
+            { type: 'string' },
+            {
+              type: 'array',
+              items: { type: 'string' }
+            }
+          ],
+          description: 'Metric fields to request (max 20 metrics). Defaults to impressions,clicks,costInLocalCurrency,externalWebsiteConversions,dateRange,pivotValues.'
+        }
+      },
+      required: ['pivot', 'start']
+    }
+  },
+  {
+    name: 'mutate',
+    description: 'Execute create/update/pause/enable/archive operations for campaign, campaign_group, and creative entities. dry_run defaults to true and returns a local-validation preview of the exact requests without calling the API (LinkedIn has no server-side validate-only mode). Creates default to DRAFT status (LinkedIn\'s safe non-serving state; pass explicit status — intendedStatus for creatives — to override). archive sets status ARCHIVED and is hard to reverse — prefer pause. Updates use Rest.li PARTIAL_UPDATE with { patch: { $set: {...} } }.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        account_id: {
+          type: 'string',
+          description: 'LinkedIn ad account ID. Supports either 123... or urn:li:sponsoredAccount:123...'
+        },
+        operations: {
+          type: 'array',
+          description: 'Array of operation objects: { entity, action, id?, params? }',
+          items: {
+            type: 'object'
+          }
+        },
+        dry_run: {
+          type: 'boolean',
+          description: 'Validate locally and preview requests only (default: true)',
+          default: true
+        },
+        partial_failure: {
+          type: 'boolean',
+          description: 'Continue executing later operations when one fails (default: true)',
+          default: true
+        }
+      },
+      required: ['operations']
+    }
+  }
+];
+
+const TOOLS = READ_ONLY ? ALL_TOOLS.filter((tool) => tool.name !== 'mutate') : ALL_TOOLS;
+
+const envStatus = validateEnvironment();
+if (!envStatus.valid) {
+  console.error(`Missing required environment variables: ${envStatus.missing.join(', ')}`);
+  process.exit(1);
+}
+
+if (READ_ONLY) {
+  console.error('Read-only mode enabled — mutate tool disabled');
+}
+
+const server = new Server(
+  {
+    name: SERVER_NAME,
+    version: SERVER_VERSION
+  },
+  {
+    capabilities: {
+      tools: {},
+      prompts: {},
+      resources: {}
+    }
+  }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: params } = request.params;
+
+  if (name === 'list_accounts') {
+    return listAccounts(params);
+  }
+
+  if (name === 'query') {
+    return query(params);
+  }
+
+  if (name === 'analytics') {
+    return analytics(params);
+  }
+
+  if (name === 'mutate') {
+    if (READ_ONLY) {
+      throw new Error('mutate is disabled in read-only mode (LINKEDIN_ADS_READ_ONLY=true)');
+    }
+    return mutate(params);
+  }
+
+  throw new Error(`Unknown tool: ${name}`);
+});
+
+server.setRequestHandler(ListPromptsRequestSchema, async () => ({ prompts: getPromptsList() }));
+server.setRequestHandler(GetPromptRequestSchema, async (request) => (
+  renderPrompt(request.params.name, request.params.arguments || {})
+));
+
+server.setRequestHandler(ListResourcesRequestSchema, async () => ({ resources: getResourcesList() }));
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => readResource(request.params.uri));
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error(`${SERVER_NAME} v${SERVER_VERSION} started`);
+}
+
+main().catch((error) => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});

package/server/prompts/templates.js

@@ -0,0 +1,134 @@
+export const PROMPT_TEMPLATES = {
+  spend_pacing_check: {
+    name: 'spend_pacing_check',
+    description: 'Check campaign spend pacing against budgets and run schedules',
+    arguments: [
+      {
+        name: 'account_id',
+        description: 'LinkedIn ad account ID (numeric, without URN prefix)',
+        required: true
+      },
+      {
+        name: 'start',
+        description: 'Analytics start date (YYYY-MM-DD)',
+        required: true
+      },
+      {
+        name: 'end',
+        description: 'Analytics end date (YYYY-MM-DD, defaults to today)',
+        required: false,
+        default: 'today'
+      }
+    ],
+    template: `Run a spend pacing check for LinkedIn ad account {{account_id}} from {{start}} to {{end}}:
+
+1. Pull active campaigns with budget and run schedule fields (query, entity=campaigns, status=ACTIVE).
+2. Pull daily spend per campaign (analytics, pivot=CAMPAIGN, time_granularity=DAILY, fields including costInLocalCurrency).
+3. Compare spend velocity to dailyBudget/totalBudget and remaining flight time.
+4. Flag campaigns underpacing and overpacing with projected end-of-flight totals.
+5. Return top pacing issues and recommended budget or schedule actions.`,
+    requiredTools: ['query', 'analytics']
+  },
+  creative_fatigue_check: {
+    name: 'creative_fatigue_check',
+    description: 'Check for creative fatigue signals and propose refresh priorities',
+    arguments: [
+      {
+        name: 'account_id',
+        description: 'LinkedIn ad account ID (numeric, without URN prefix)',
+        required: true
+      },
+      {
+        name: 'start',
+        description: 'Analytics start date (YYYY-MM-DD)',
+        required: true
+      }
+    ],
+    template: `Run a creative fatigue analysis for LinkedIn ad account {{account_id}} starting {{start}}:
+
+1. Pull active campaigns (query, entity=campaigns, status=ACTIVE), then their creatives (query, entity=creatives with campaign_ids).
+2. Pull creative-level metrics over time (analytics, pivot=CREATIVE, entity_type=campaign with the active campaign IDs, time_granularity=DAILY, fields=impressions,clicks,costInLocalCurrency,dateRange,pivotValues).
+3. Flag creatives with high cumulative impressions and declining click-through trend.
+4. Group fatigued creatives by campaign and estimate wasted spend.
+5. Return prioritized creative refresh recommendations with rationale.`,
+    requiredTools: ['query', 'analytics']
+  },
+  campaign_performance_audit: {
+    name: 'campaign_performance_audit',
+    description: 'Audit account performance by campaign group and campaign',
+    arguments: [
+      {
+        name: 'account_id',
+        description: 'LinkedIn ad account ID (numeric, without URN prefix)',
+        required: true
+      },
+      {
+        name: 'start',
+        description: 'Analytics start date (YYYY-MM-DD)',
+        required: true
+      },
+      {
+        name: 'end',
+        description: 'Analytics end date (YYYY-MM-DD, defaults to today)',
+        required: false,
+        default: 'today'
+      }
+    ],
+    template: `Run a performance audit for LinkedIn ad account {{account_id}} from {{start}} to {{end}}:
+
+1. Pull campaign groups and campaigns with status and budget fields (query).
+2. Pull metrics pivoted by CAMPAIGN_GROUP and by CAMPAIGN (analytics, fields=impressions,clicks,costInLocalCurrency,externalWebsiteConversions,pivotValues).
+3. Compute CTR, CPC, and cost per conversion for each campaign.
+4. Rank campaigns by efficiency and flag spend concentrated in weak performers.
+5. Return a prioritized list of scale, fix, and pause recommendations.`,
+    requiredTools: ['query', 'analytics']
+  }
+};
+
+export function getPromptDefinition(name) {
+  return PROMPT_TEMPLATES[name] || null;
+}
+
+export function getPromptsList() {
+  return Object.values(PROMPT_TEMPLATES).map((prompt) => ({
+    name: prompt.name,
+    description: prompt.description,
+    arguments: prompt.arguments
+  }));
+}
+
+export function renderPrompt(name, args = {}) {
+  const template = PROMPT_TEMPLATES[name];
+  if (!template) {
+    throw new Error(`Unknown prompt: ${name}. Available prompts: ${Object.keys(PROMPT_TEMPLATES).join(', ')}`);
+  }
+
+  const missing = template.arguments
+    .filter((argument) => argument.required && !args[argument.name])
+    .map((argument) => argument.name);
+
+  if (missing.length > 0) {
+    throw new Error(`Missing required arguments for prompt "${name}": ${missing.join(', ')}`);
+  }
+
+  let text = template.template;
+
+  for (const argument of template.arguments) {
+    const value = args[argument.name] ?? argument.default;
+    if (value !== undefined) {
+      text = text.replace(new RegExp(`\\{\\{${argument.name}\\}\\}`, 'g'), String(value));
+    }
+  }
+
+  return {
+    messages: [
+      {
+        role: 'user',
+        content: {
+          type: 'text',
+          text
+        }
+      }
+    ]
+  };
+}

package/server/resources/analytics-fields-reference.md

@@ -0,0 +1,63 @@
+# LinkedIn Ads Analytics Field Reference
+
+Reference for the `analytics` tool, which wraps `GET /rest/adAnalytics?q=analytics`.
+
+## Pivots Supported by This Server
+
+| Pivot | Groups results by |
+|-------|--------------------|
+| `ACCOUNT` | Ad account |
+| `CAMPAIGN_GROUP` | Campaign group |
+| `CAMPAIGN` | Campaign |
+| `CREATIVE` | Creative |
+
+LinkedIn also offers demographic pivots (e.g. `MEMBER_COMPANY`, `MEMBER_JOB_TITLE`, `MEMBER_INDUSTRY`) which this server does not expose; demographic reporting has extra minimum-audience restrictions and different field availability.
+
+## Time Granularity
+
+| Value | Meaning |
+|-------|---------|
+| `ALL` | One row per pivot value for the whole date range (default) |
+| `DAILY` | One row per pivot value per day |
+| `MONTHLY` | One row per pivot value per calendar month |
+
+## Default Fields
+
+If you pass no `fields`, the server requests:
+
+```
+impressions, clicks, costInLocalCurrency, externalWebsiteConversions, dateRange, pivotValues
+```
+
+`dateRange` and `pivotValues` are dimensional fields (they tell you which slice a row describes); the rest are metrics. LinkedIn allows at most **20 metric fields per call** and returns only `impressions` and `clicks` if you omit the `fields` parameter entirely.
+
+## Commonly Used Metric Fields
+
+| Field | Description |
+|-------|-------------|
+| `impressions` | Sponsored impressions served |
+| `clicks` | Chargeable clicks |
+| `costInLocalCurrency` | Spend in the account currency |
+| `costInUsd` | Spend converted to USD |
+| `externalWebsiteConversions` | Conversions tracked via the Insight Tag |
+| `externalWebsitePostClickConversions` | Post-click conversions |
+| `externalWebsitePostViewConversions` | Post-view (view-through) conversions |
+| `landingPageClicks` | Clicks to the landing page |
+| `likes` | Reactions on sponsored content |
+| `comments` | Comments on sponsored content |
+| `shares` | Shares of sponsored content |
+| `follows` | Follows generated |
+| `totalEngagements` | All chargeable and free engagements |
+| `videoViews` | Video views (2+ continuous seconds or click) |
+| `videoCompletions` | Video watched to 97-100% |
+| `oneClickLeads` | Leads from Lead Gen Forms |
+| `oneClickLeadFormOpens` | Lead Gen Form opens |
+| `conversionValueInLocalCurrency` | Value of conversions in account currency |
+
+Derived rates (CTR, CPC, CPM, cost per conversion) are not returned by the API; compute them from the raw fields.
+
+## Practical Limits
+
+- No pagination: responses are capped at 15,000 elements. Narrow the date range, granularity, or entity list if you hit the cap.
+- Long entity URN lists can push the request URL past server limits (HTTP 414); split large ID lists across multiple calls.
+- Metrics are eventually consistent; very recent data (same day) may still change.

package/server/resources/index.js

@@ -0,0 +1,65 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * Static list of resource documents exposed by the server.
+ */
+export const RESOURCES = [
+  {
+    uri: 'linkedinads://reference',
+    name: 'LinkedIn Marketing API Reference',
+    description: 'Core versioned REST endpoints, required headers, Rest.li 2.0 encoding, and finder syntax for LinkedIn Ads workflows',
+    mimeType: 'text/markdown'
+  },
+  {
+    uri: 'linkedinads://analytics-fields',
+    name: 'LinkedIn Ads Analytics Field Reference',
+    description: 'adAnalytics pivots, time granularities, and commonly used metric fields with defaults',
+    mimeType: 'text/markdown'
+  },
+  {
+    uri: 'linkedinads://rate-limits',
+    name: 'LinkedIn Ads Rate Limits and Quotas',
+    description: 'Rate limiting behavior, backoff guidance, and operational recommendations',
+    mimeType: 'text/markdown'
+  }
+];
+
+const RESOURCE_FILE_MAP = {
+  'linkedinads://reference': 'marketing-api-reference.md',
+  'linkedinads://analytics-fields': 'analytics-fields-reference.md',
+  'linkedinads://rate-limits': 'rate-limits-and-quotas.md'
+};
+
+export function getResourcesList() {
+  return RESOURCES;
+}
+
+/**
+ * Read a resource document by URI.
+ * @param {string} uri
+ * @returns {{ contents: Array<{ uri: string, mimeType: string, text: string }> }}
+ */
+export function readResource(uri) {
+  const filename = RESOURCE_FILE_MAP[uri];
+  if (!filename) {
+    throw new Error(`Unknown resource: ${uri}. Available: ${Object.keys(RESOURCE_FILE_MAP).join(', ')}`);
+  }
+
+  const filePath = join(__dirname, filename);
+  const content = readFileSync(filePath, 'utf8');
+
+  return {
+    contents: [
+      {
+        uri,
+        mimeType: 'text/markdown',
+        text: content
+      }
+    ]
+  };
+}

package/server/resources/marketing-api-reference.md

@@ -0,0 +1,98 @@
+# LinkedIn Marketing API Reference
+
+LinkedIn Ads uses the versioned REST API at `https://api.linkedin.com/rest`. Every request needs three headers:
+
+| Header | Value |
+|--------|-------|
+| `Authorization` | `Bearer <access token>` |
+| `LinkedIn-Version` | `YYYYMM` (this server defaults to `202605`, override via `LINKEDIN_ADS_API_VERSION`) |
+| `X-Restli-Protocol-Version` | `2.0.0` |
+
+API versions are released monthly and supported for roughly one year. If requests start failing with version errors, set `LINKEDIN_ADS_API_VERSION` to a newer `YYYYMM` value.
+
+## Rest.li 2.0 Query Encoding
+
+Structured query parameters are NOT standard URL encoding:
+
+- List parameters: `campaigns=List(urn%3Ali%3AsponsoredCampaign%3A123,urn%3Ali%3AsponsoredCampaign%3A456)` — the `List(` wrapper, commas, and parens are literal; each item (URNs included) is percent-encoded.
+- Date ranges: `dateRange=(start:(year:2026,month:6,day:1),end:(year:2026,month:6,day:30))` — parens, colons, and commas literal; no leading zeros.
+- Finder search filters: `search=(status:(values:List(ACTIVE,PAUSED)))`.
+
+Never run these through `URLSearchParams`; it would percent-encode the structural characters and break the request.
+
+## Core Endpoints Used by This Server
+
+### Ad Accounts
+
+```
+GET /rest/adAccounts?q=search&pageSize=1000
+GET /rest/adAccounts?q=search&search=(status:(values:List(ACTIVE)),type:(values:List(BUSINESS)))
+```
+
+- Cursor pagination: pass `pageSize` (max 1000) and the `pageToken` from the previous response's `metadata.nextPageToken`.
+- Account statuses: `ACTIVE`, `CANCELED`, `DRAFT`, `PENDING_DELETION`, `REMOVED`.
+- Account types: `BUSINESS`, `ENTERPRISE`.
+
+### Campaign Groups and Campaigns
+
+```
+GET /rest/adAccounts/{accountId}/adCampaignGroups?q=search
+GET /rest/adAccounts/{accountId}/adCampaigns?q=search&search=(status:(values:List(ACTIVE)))
+POST /rest/adAccounts/{accountId}/adCampaigns            (create; 201 + id in x-restli-id header)
+POST /rest/adAccounts/{accountId}/adCampaigns/{id}       (partial update; see below)
+```
+
+- Campaign statuses: `ACTIVE`, `PAUSED`, `ARCHIVED`, `COMPLETED`, `CANCELED`, `DRAFT`, `PENDING_DELETION`, `REMOVED`.
+- Same finder/pagination pattern as adAccounts (`pageSize` max 1000).
+
+### Creatives
+
+```
+GET /rest/adAccounts/{accountId}/creatives?q=criteria&intendedStatuses=List(ACTIVE)&campaigns=List(urn%3Ali%3AsponsoredCampaign%3A123)
+POST /rest/adAccounts/{accountId}/creatives              (create; id URN in x-restli-id header)
+POST /rest/adAccounts/{accountId}/creatives/{encodedUrn} (partial update)
+```
+
+- Creatives use the `criteria` finder with top-level List params, not a `search` expression.
+- `pageSize` max is 100 for creatives.
+- Creative IDs are URNs (`urn:li:sponsoredCreative:123`) and must be percent-encoded in resource paths.
+- Creative status lives in `intendedStatus`; actual delivery state is reflected by `isServing` / `servingHoldReasons`.
+
+### Partial Updates
+
+Updates and status changes use Rest.li partial update: POST to the entity item with header `X-RestLi-Method: PARTIAL_UPDATE` and body:
+
+```json
+{ "patch": { "$set": { "status": "PAUSED" } } }
+```
+
+A successful partial update returns `204 No Content`.
+
+### Analytics
+
+```
+GET /rest/adAnalytics?q=analytics&pivot=CAMPAIGN&dateRange=(start:(year:2026,month:6,day:1))&timeGranularity=DAILY&campaigns=List(urn%3Ali%3AsponsoredCampaign%3A123)&fields=impressions,clicks,costInLocalCurrency,externalWebsiteConversions,dateRange,pivotValues
+```
+
+- No pagination; responses are capped at 15,000 elements.
+- At most 20 metric fields per call.
+- Very long URN lists can exceed URL length limits (HTTP 414); split entity lists across calls if needed.
+
+## Response Envelope
+
+Finder responses return:
+
+```json
+{
+  "elements": [ ... ],
+  "metadata": { "nextPageToken": "..." },
+  "paging": { ... }
+}
+```
+
+Error responses include `status`, `code`/`serviceErrorCode`, and `message` fields.
+
+## Auth
+
+- Static token: `LINKEDIN_ADS_ACCESS_TOKEN` (60-day member tokens from the 3-legged OAuth flow).
+- Programmatic refresh: POST `https://www.linkedin.com/oauth/v2/accessToken` (form-encoded) with `grant_type=refresh_token`, `refresh_token`, `client_id`, `client_secret`. Refresh tokens last one year from issuance and are not extended by refreshing.

package/server/resources/rate-limits-and-quotas.md

@@ -0,0 +1,34 @@
+# LinkedIn Ads Rate Limits and Quotas
+
+LinkedIn Marketing API throttling is quota-based: each application has daily application-level and member-level (per token) limits per endpoint. Exact numbers vary by endpoint and program tier and are visible in the LinkedIn Developer Portal under your app's Analytics > Quotas view. Quotas reset daily (midnight UTC).
+
+## What This MCP Server Does
+
+- Treats HTTP `429` as the throttling signal.
+- Reads the `Retry-After` response header when available.
+- Falls back to `60` seconds if `Retry-After` is missing or invalid.
+- Retries throttled requests once.
+
+## Backoff Behavior
+
+`Retry-After` values may be:
+
+- Integer seconds (for example `7`)
+- HTTP date string
+
+The server converts this to milliseconds and sleeps before a single retry. If the retry is throttled again, the error is surfaced to the caller.
+
+## Timeout Behavior
+
+- Requests use a default timeout of `30000` ms.
+- Override with `LINKEDIN_ADS_REQUEST_TIMEOUT_MS` environment variable.
+- Timeout errors are surfaced as request failures so callers can retry or degrade gracefully.
+
+## Operational Guidance
+
+- Keep `fields` projections narrow on analytics calls (max 20 metrics anyway).
+- Use `limit` deliberately; every extra page is another quota hit.
+- Batch analytics by passing multiple entity IDs in one call instead of one call per entity — but watch URL length (HTTP 414 means split the list).
+- Cache read-heavy metadata (account and campaign lists) where possible.
+- Stagger high-volume jobs; daily quotas exhaust silently until requests start failing with 429s.
+- If you consistently hit quota ceilings, apply for a higher access tier in the LinkedIn Developer Portal.