Social Fetch
Get API key
GitHub hub

GitHub contribution graph API

Pull a public GitHub contribution heatmap for a login and calendar year — yearly total plus per-day counts, color, and intensity — in the shared Social Fetch envelope.

GET /v1/github/profiles/{handle}/contributions

1 credit per successful request.

Try in playgroundFull API docs

About this endpoint

Recruiting scorecards, open-source health checks, and founder enrichment often need the green squares, not just a follower count. You already have a GitHub login. You want `totalContributions` for a year and a day-by-day series you can chart or store. Scraping the profile HTML or wiring a personal access token for that one graph is more ops than the job deserves.

`GET /v1/github/profiles/{handle}/contributions` takes the GitHub username (login) in the path. Optional query param `year` is a calendar year from 2007 through 2100; omit it to use the current year. Send `x-api-key`. Branch on `data.lookupStatus` before you write: `found` vs `not_found`. On `found`, `data.contributions` includes `handle`, `year`, `totalContributions`, and `days` — each day has `date` (YYYY-MM-DD), `contributionCount`, optional `color`, and `intensity`. On `not_found`, `contributions` is null.

This route is the yearly heatmap. Narrative month groups and event-style activity live on `GET /v1/github/profiles/{handle}/activity`. The profile card and aggregate metrics are `GET /v1/github/profiles/{handle}`. Credit pricing for this operation is shown on this page; trust `meta.creditsCharged` on every response.

GitHub contribution graph API FAQ

How do I fetch a GitHub contribution graph via API?

Call GET /v1/github/profiles/{handle}/contributions with your Social Fetch API key in the x-api-key header. Pass the public GitHub username (login) as the path parameter. Optionally set year (2007–2100); omit it for the current year. Read data.lookupStatus, then data.contributions. Full parameters and examples are in the API docs linked from this page.

How much does the GitHub contributions API cost?

Pricing is documented on the operation in the API registry (shown on this page). Confirm on every response with meta.creditsCharged — that field is the billing source of truth.

What does the contributions response include?

On found, data.contributions has handle, year, totalContributions, and days. Each day includes date (YYYY-MM-DD), contributionCount, optional color, and intensity. Exact nullability lives in the OpenAPI schema for this route.

How do I pick the calendar year for the heatmap?

Pass year as an optional integer query param between 2007 and 2100. When omitted, the API uses the current calendar year. Each request covers one year; call again with a different year for historical windows.

What does lookupStatus mean on the contributions route?

found means contribution data could be returned for that login and year. not_found means no public match; contributions is null. Always branch on lookupStatus before treating a missing graph as zero contributions.

How is this different from the GitHub profile activity route?

This endpoint returns the contribution heatmap (totals and per-day cells) for one year. GET /v1/github/profiles/{handle}/activity returns grouped activity detail rows for a profile. Use contributions for charts and streak-style signals; use activity for narrative event groups.

Do I need a GitHub personal access token or OAuth app?

No. Social Fetch authenticates with your Social Fetch API key only. You do not create a GitHub OAuth app or pass a personal access token for this public contributions route.

Can I use this for recruiting or open-source activity scoring?

Yes. Teams load totalContributions and the days series into candidate or maintainer scorecards, then pair the graph with the profile or repositories routes when they need identity or repo inventory. Keep meta.requestId if you need support on a failed lookup.

Other GitHub endpoints