https://octocounts.com/docs/api

1<!doctype html>
2<html lang="en">
3  <head>
4    <meta charset="utf-8" />
5    <meta name="viewport" content="width=device-width, initial-scale=1" />
6    <title>OctoCounts API Docs | Public Repository SLOC API</title>
7    <meta name="description" content="OctoCounts API documentation for public GitHub repository SLOC analysis, reports, jobs, badges, compare URLs, and diff URLs." />
8    <meta name="robots" content="index,follow,max-image-preview:large,max-snippet:-1" />
9    <link rel="canonical" href="https://octocounts.com/docs/api" />
10    <link rel="alternate" type="text/markdown" href="https://octocounts.com/docs/api.md" />
11    <meta property="og:type" content="article" />
12    <meta property="og:site_name" content="OctoCounts" />
13    <meta property="og:title" content="OctoCounts API Docs" />
14    <meta property="og:description" content="Analyze public GitHub repositories, poll jobs, fetch SLOC reports, and generate live badges through the OctoCounts API." />
15    <meta property="og:url" content="https://octocounts.com/docs/api" />
16    <meta property="og:image" content="https://octocounts.com/og-image.jpg" />
17    <meta name="twitter:card" content="summary_large_image" />
18    <meta name="twitter:title" content="OctoCounts API Docs" />
19    <meta name="twitter:description" content="Public repository SLOC analysis API, report fields, job polling, and badge routes." />
20    <meta name="twitter:image" content="https://octocounts.com/og-image.jpg" />
21    <style>
22      * { box-sizing: border-box; }
23      body { max-width: 880px; margin: 40px auto; padding: 0 20px; font: 15px/1.6 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; color: #1f2328; overflow-x: hidden; }
24      h1, h2 { line-height: 1.2; }
25      code, pre { background: #f6f8fa; border: 1px solid #d0d7de; border-radius: 4px; }
26      code { padding: 1px 4px; overflow-wrap: anywhere; }
27      pre { max-width: 100%; padding: 12px; overflow: auto; }
28      pre code { overflow-wrap: normal; }
29      a { color: #0969da; }
30      .note { border-left: 3px solid #1a7f37; padding-left: 12px; color: #57606a; }
31    </style>
32    

32<script type="application/ld+json">
33    {
34      "@context": "https://schema.org",
35      "@type": "TechArticle",
36      "headline": "OctoCounts API Docs",
37      "description": "API documentation for public GitHub repository SLOC analysis, jobs, reports, badges, compare URLs, and diff URLs.",
38      "datePublished": "2026-06-12",
39      "dateModified": "2026-09-30",
40      "mainEntityOfPage": "https://octocounts.com/docs/api",
41      "speakable": {
42        "@type": "SpeakableSpecification",
43        "cssSelector": ["h1", ".answer"]
44      },
45      "author": {
46        "@type": "Person",
47        "@id": "https://github.com/huanglizhuo",
48        "name": "huanglizhuo",
49        "url": "https://github.com/huanglizhuo"
50      },
51      "publisher": {
52        "@type": "Organization",
53        "@id": "https://octocounts.com/#organization",
54        "name": "OctoCounts",
55        "url": "https://octocounts.com/"
56      }
57    }
58    </script>

58
59    

59<script type="application/ld+json">
60    {
61      "@context": "https://schema.org",
62      "@type": "BreadcrumbList",
63      "itemListElement": [
64        { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://octocounts.com/" },
65        { "@type": "ListItem", "position": 2, "name": "Docs", "item": "https://octocounts.com/docs" },
66        { "@type": "ListItem", "position": 3, "name": "OctoCounts API Docs", "item": "https://octocounts.com/docs/api" }
67      ]
68    }
69    </script>

69
70    

70<script type="application/ld+json">
71    {
72      "@context": "https://schema.org",
73      "@type": "FAQPage",
74      "mainEntity": [
75        {
76          "@type": "Question",
77          "name": "Do I need an API key or account to use the OctoCounts API?",
78          "acceptedAnswer": {
79            "@type": "Answer",
80            "text": "No. The OctoCounts API requires no GitHub account access, no API token, and no sign-up. It analyzes public github.com repositories only, does not support private repositories, and does not accept source-code uploads."
81          }
82        },
83        {
84          "@type": "Question",
85          "name": "How do I analyze a public GitHub repository?",
86          "acceptedAnswer": {
87            "@type": "Answer",
88            "text": "POST https://api.octocounts.com/api/analyze with a JSON body containing repoUrl and optionally refName, forceRefresh, source, and analysis options such as ignoredDirs, ignoredLanguages, includeDocs, includeTests, and includeGenerated. refName may be a branch, tag, or commit SHA; if omitted, the repository default branch is used."
89          }
90        },
91        {
92          "@type": "Question",
93          "name": "How do I check the status of an analysis job?",
94          "acceptedAnswer": {
95            "@type": "Answer",
96            "text": "Poll GET https://api.octocounts.com/api/jobs/:jobId. Jobs return queued, running, completed, or failed, and completed jobs include a reportId that you pass to the report endpoint."
97          }
98        },
99        {
100          "@type": "Question",
101          "name": "What does an OctoCounts report contain?",
102          "acceptedAnswer": {
103            "@type": "Answer",
104            "text": "GET https://api.octocounts.com/api/reports/:reportId returns repository metadata, the pinned commit SHA, the tokei version used, the analysis key, the active analysis options, per-language rows, and totals for files, lines, code, comments, and blanks."
105          }
106        },
107        {
108          "@type": "Question",
109          "name": "How do I add a SLOC badge to my README?",
110          "acceptedAnswer": {
111            "@type": "Answer",
112            "text": "Request https://api.octocounts.com/badge/:owner/:repo with optional type parameters such as code, lines, files, comments, languages, top-language, or ratio, and optional branch, tag, or commit path segments. Wrap the badge URL in a Markdown image that links to the permanent OctoCounts report page."
113          }
114        },
115        {
116          "@type": "Question",
117          "name": "What shareable URLs does OctoCounts provide?",
118          "acceptedAnswer": {
119            "@type": "Answer",
120            "text": "Every analyzed repository gets permanent web URLs such as https://octocounts.com/github/:owner/:repo, plus ref, compare, and diff URLs, so a report can be cited and shared without re-running the analysis."
121          }
122        }
123      ]
124    }
125    </script>

125
126    

126<script type="application/ld+json">
127    {
128      "@context": "https://schema.org",
129      "@type": "Person",
130      "@id": "https://github.com/huanglizhuo",
131      "name": "huanglizhuo",
132      "url": "https://github.com/huanglizhuo",
133      "sameAs": [
134        "https://github.com/huanglizhuo",
135        "https://github.com/huanglizhuo/OctoCounts",
136        "https://chromewebstore.google.com/detail/octocounts-%E2%80%94-github-sloc/gkgjpjdnaklagijmekoolhcpebmoldbj",
137        "https://microsoftedge.microsoft.com/addons/detail/octocounts-%E2%80%93-github-sloc-/ehifednhpbpekkadndaipnngopbhpoim",
138        "https://addons.mozilla.org/en-US/firefox/addon/octocounts-github-sloc/",
139        "https://www.npmjs.com/package/octocounts"
140      ],
141      "knowsAbout": ["source lines of code", "code metrics", "tokei", "developer tools"]
142    }
143    </script>

143
144  </head>
145  <body>
146    <h1>OctoCounts API Docs</h1>
147    <p class="answer">OctoCounts is a free API for counting source lines of code in public GitHub repositories. A client posts a repository URL and an optional branch, tag, or commit SHA to the analyze endpoint, polls the returned job, and fetches a report with files, total lines, code lines, comments, blanks, and per-language totals. No account or API token is required, and reports are cached by commit SHA, tokei version, and analysis options.</p>
148    <p class="meta">Updated September 16, 2026 &middot; Maintained by <a href="https://github.com/huanglizhuo">huanglizhuo</a></p>
149    <p class="note">OctoCounts analyzes public GitHub repositories only. It does not request GitHub account access, does not support private repositories, and does not accept source-code uploads.</p>
150
151    <h2>How do I analyze a public GitHub repository?</h2>
152    <pre><code>POST https://api.octocounts.com/api/analyze
153Content-Type: application/json
154
155{
156  "repoUrl": "https://github.com/owner/repo",
157  "refName": "main",
158  "forceRefresh": false,
159  "source": "api",
160  "options": {
161    "profile": "default",
162    "ignoredDirs": [],
163    "ignoredLanguages": [],
164    "includeDocs": true,
165    "includeTests": true,
166    "includeGenerated": true
167  }
168}</code></pre>
169    <p><code>repoUrl</code> supports public <code>github.com</code> repositories. <code>refName</code> may be a branch, tag, or commit SHA. If omitted, OctoCounts uses the repository default branch. <code>source</code> is optional and may be <code>web</code>, <code>extension</code>, <code>github_action</code>, <code>cli</code>, <code>mcp</code>, <code>api</code>, <code>seed</code>, <code>github_trending</code>, <code>sloc_backfill</code>, or <code>unknown</code>; it is used only for aggregate source breakdowns.</p>
170
171    <h2>How do I check the status of an analysis job?</h2>
172    <pre><code>GET https://api.octocounts.com/api/jobs/:jobId</code></pre>
173    <p>Jobs return <code>queued</code>, <code>running</code>, <code>completed</code>, or <code>failed</code>. Completed jobs include <code>reportId</code>.</p>
174
175    <h2>What does an OctoCounts report contain?</h2>
176    <pre><code>GET https://api.octocounts.com/api/reports/:reportId</code></pre>
177    <p>Reports include repository metadata, pinned commit SHA, tokei version, analysis key, active analysis options, language rows, and totals for files, lines, code, comments, and blanks.</p>
178
179    <h2>What public stats are available?</h2>
180    <pre><code>GET https://api.octocounts.com/api/stats</code></pre>
181    <p>Returns aggregate operational stats: total reports generated, unique public repositories analyzed, total lines counted, source breakdown, language totals, recent reports, and largest public repositories. This endpoint does not expose user-level analytics.</p>
182
183    <h2>Which endpoints power indexable pages and OG images?</h2>
184    <pre><code>GET https://api.octocounts.com/api/seo/report?provider=github&amp;owner=owner&amp;repo=repo
185GET https://api.octocounts.com/api/seo/recent
186GET https://api.octocounts.com/api/seo/popular
187GET https://api.octocounts.com/api/seo/monoliths
188GET https://api.octocounts.com/api/seo/sitemap
189GET https://api.octocounts.com/og/github/:owner/:repo</code></pre>
190    <p>These endpoints power indexable report pages on <code>octocounts.com</code>. They return cached report metadata only; they do not start new analyses.</p>
191
192    <h2>How do I generate a SLOC badge for a repository?</h2>
193    <pre><code>GET https://api.octocounts.com/badge/:owner/:repo
194GET https://api.octocounts.com/badge/:owner/:repo/branch/:branch
195GET https://api.octocounts.com/badge/:owner/:repo/tag/:tag
196GET https://api.octocounts.com/badge/:owner/:repo/commit/:sha</code></pre>
197    <p>Badge query parameters:</p>
198    <ul>
199      <li><code>type=code</code>, <code>lines</code>, <code>files</code>, <code>comments</code>, <code>languages</code>, <code>top-language</code>, or <code>ratio</code></li>
200      <li><code>lang=Rust</code> for a single-language code-line badge</li>
201    </ul>
202
203    <h2>

203What shareable web URLs does OctoCounts provide?</h2>
204    <pre><code>https://octocounts.com/github/:owner/:repo
205https://octocounts.com/github/:owner/:repo/tree/:ref
206https://octocounts.com/github/:owner/:repo/commit/:sha
207https://octocounts.com/compare?left=...&amp;right=...&amp;leftRef=...&amp;rightRef=...
208https://octocounts.com/diff?repo=...&amp;base=...&amp;head=...</code></pre>
209
210    <h2>Where are the methodology and AI-readable context documented?</h2>
211    <p>For citation details, cache keys, ignored folders, and counting limitations, see the <a href="/docs/methodology">OctoCounts methodology</a>. Agent-readable context is available at <a href="/llms.txt">/llms.txt</a> and <a href="/llms-full.txt">/llms-full.txt</a>.</p>
212
213    <h2>Frequently Asked Questions</h2>
214
215    <h3>Do I need an API key or account to use the OctoCounts API?</h3>
216    <p>No. The OctoCounts API requires no GitHub account access, no API token, and no sign-up. It analyzes public github.com repositories only, does not support private repositories, and does not accept source-code uploads.</p>
217
218    <h3>How do I analyze a public GitHub repository?</h3>
219    <p>POST <code>https://api.octocounts.com/api/analyze</code> with a JSON body containing <code>repoUrl</code> and optionally <code>refName</code>, <code>forceRefresh</code>, <code>source</code>, and analysis options. <code>refName</code> may be a branch, tag, or commit SHA; if omitted, OctoCounts uses the repository default branch.</p>
220
221    <h3>How do I check the status of an analysis job?</h3>
222    <p>Poll <code>GET https://api.octocounts.com/api/jobs/:jobId</code>. Jobs return <code>queued</code>, <code>running</code>, <code>completed</code>, or <code>failed</code>, and completed jobs include a <code>reportId</code> that you pass to the report endpoint.</p>
223
224    <h3>What does an OctoCounts report contain?</h3>
225    <p><code>GET https://api.octocounts.com/api/reports/:reportId</code> returns repository metadata, the pinned commit SHA, the tokei version used, the analysis key, the active analysis options, per-language rows, and totals for files, lines, code, comments, and blanks.</p>
226
227    <h3>How do I add a SLOC badge to my README?</h3>
228    <p>Request <code>https://api.octocounts.com/badge/:owner/:repo</code> with optional <code>type</code> parameters (<code>code</code>, <code>lines</code>, <code>files</code>, <code>comments</code>, <code>languages</code>, <code>top-language</code>, or <code>ratio</code>) and optional branch, tag, or commit path segments. Wrap the badge URL in a Markdown image that links to the permanent OctoCounts report page.</p>
229
230    <h3>What shareable URLs does OctoCounts provide?</h3>
231    <p>Every analyzed repository gets permanent web URLs such as <code>https://octocounts.com/github/:owner/:repo</code>, plus ref, compare, and diff URLs, so a report can be cited and shared without re-running the analysis.</p>
232
233    <p><a href="/">Back to OctoCounts</a></p>
234  <!-- Cloudflare Pages Analytics -->

234<script defer src='https://static.cloudflareinsights.com/beacon.min.js' data-cf-beacon='{"token": "

23471af94b0ca2c4711a817b0cb99d9eb5b

234"}'></script>

234<!-- Cloudflare Pages Analytics -->

234<script>(function(){function c(){var b=a.contentDocument||(a.contentWindow&&a.contentWindow.document);if(b){var d=b.createElement('script');d.innerHTML="window.__CF$cv$params={r:'a43f9b9239b2863e',t:'MTc5MDkwMTEyMg=='};var a=document.createElement('script');a.src='/cdn-cgi/challenge-platform/scripts/jsd/main.js';document.getElementsByTagName('head')[0].appendChild(a);";b.getElementsByTagName('head')[0].appendChild(d)}}if(document.body){var a=document.createElement('iframe');a.height=1;a.width=1;a.style.position='absolute';a.style.top=0;a.style.left=0;a.style.border='none';a.style.visibility='hidden';document.body.appendChild(a);if('loading'!==document.readyState)c();else if(window.addEventListener)document.addEventListener('DOMContentLoaded',c);else{var e=document.onreadystatechange||function(){};document.onreadystatechange=function(b){e(b);'loading'!==document.readyState&&(document.onreadystatechange=e,c())}}}})();</script>

234<script type="module" src="https://static.cloudflareinsights.com/beacon.min.js/v31edd6df95cf4e85bb4c19e7a9bdbcba1788362987495" integrity="sha512-iIg7k2xntmwu6/uSb5tpc/hySgZc4eoL31yB29W6tJFo2akwjPWcEqnCEdJvGexCL0KEQwVYv5BlowfhVz26hg==" data-cf-beacon='{"version":"2024.11.0","token":"236ed5144ce44b0c9b780a2b74cdf95f","r":1,"spa":2}' crossorigin="anonymous"></script>

234
235</body>
236</html>