onenote-cost-tuning

name	onenote-cost-tuning
description	Optimize costs and API usage for OneNote Graph API integrations with caching and batching strategies. Use when reducing API call volume, planning capacity, or evaluating OneNote integration costs. Trigger with "onenote costs", "onenote api usage", "onenote optimization", "graph api billing onenote".
allowed-tools	Read, Write, Edit, Grep
version	1.6.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","onenote","microsoft"]
compatibility	Designed for Claude Code

OneNote Cost Tuning

Overview

OneNote Graph API calls have no per-request cost — they are included in every Microsoft 365 E3/E5/Business license. However, rate limits create an effective ceiling that functions like a cost constraint: 600 requests per user per 60 seconds and 10,000 requests per app per 10 minutes at the tenant level. Exceeding these limits returns 429 errors with Retry-After headers, degrading user experience the same way budget overruns degrade service. This skill covers the practical optimization strategies that keep you well under those ceilings: metadata caching, JSON batch requests, delta sync, payload minimization with $select/$expand, and content deduplication. A naive integration that polls every user's notebooks every minute burns through the tenant limit in under 10 minutes. An optimized one handles thousands of users within the same budget.

Prerequisites

• Microsoft 365 license (E3/E5/Business) — OneNote API is included, no additional billing
• Azure AD app registration with delegated permissions
• Python: pip install msgraph-sdk azure-identity or Node: npm install @microsoft/microsoft-graph-client @azure/identity
• Understanding of HTTP caching headers (ETag, If-None-Match)

Instructions

Licensing Model and True Cost

Component	Cost
OneNote API calls	Included in M365 license (no per-call charge)
Rate limit: per user	600 requests / 60 seconds
Rate limit: per tenant	10,000 requests / 10 minutes
Retry-After penalty	Blocked for N seconds (header value)
Graph metered billing	Optional; extends limits for high-volume apps

The real cost is operational: every 429 response adds latency, retry logic consumes compute, and throttled users see failures. Optimization is about reliability, not billing.

Strategy 1: Cache Metadata Aggressively

Notebook and section metadata changes rarely (names, IDs, hierarchy). Cache it locally and refresh on a schedule, not per-request:

interface CachedMetadata {
  notebooks: any[];
  sections: Map<, []>;  
  : ;
  : ;
}

  {
   :  = {
    : [],
    :  (),
    : ,
    :  *  * ,  
  };

  ():  {
     .() - .. > ..;
  }

   (: ): <[]> {
     (!.() && ... > ) {
       ..;  
    }
     response =  client.()
      .()
      .();
    .. = response.;
    .. = .();
     ..;  
  }

   (: , : ): <[]> {
     (!.() && ...(notebookId)) {
       ...(notebookId)!;
    }
     response =  client
      .()
      .()
      .();
    ...(notebookId, response.);
     response.;
  }

  ():  {
    .. = ;
  }
}