# Contribution Calendar

Schemas

An account's contributions on each day of a year or the last twelve months: per-day counts, the platform's shade for each day, and the total.

## Endpoints

1 endpoint returns contribution calendars on GitHub.

- [GETGitHub Contributions API`/v1/github/contributions`](https://socialtap.dev/docs/reference/github/contributions/index.md)

## Schema

Every endpoint above returns this object as `data`. The standard [`meta`](https://socialtap.dev/docs/reference/index.md#meta) comes with every response.

| Field | Type | Description |
| --- | --- | --- |
| `platform` | `string` | Platform ID (github, …). |
| `url` | `string` (uri) | The public page that shows this calendar: the account's page, with the period selected where the platform links one (GitHub's year links). |
| `account` | `object` | The account whose contributions these are; at least its username. |
| `account.id` | `string` or `null` | Platform-native account ID; null when only the handle is known. |
| `account.username` | `string` or `null` | Handle without the @; null when the account has none. |
| `account.display_name` | `string` or `null` | Display name shown on the profile. |
| `account.url` | `string` (uri) or `null` | Canonical profile URL. |
| `account.avatar_url` | `string` (uri) or `null` | Profile picture URL. Platform CDN URLs can expire within hours. |
| `account.is_verified` | `boolean` or `null` | Platform verification badge; null where the platform has no badge. |
| `year` | `integer` or `null` | The calendar year the period is, when it is one (January 1 to December 31, cut at today for the current year); null when the period is the trailing twelve months. |
| `start_date` | `string` (date) | First day of the period, YYYY-MM-DD (days\[0\].date). |
| `end_date` | `string` (date) | Last day of the period, inclusive, YYYY-MM-DD (the last of days\[\]); today when the period runs to now: days to come are never listed. |
| `days` | `object[]` | Every day of the period, oldest first, one per date from start_date to end_date: days without contributions included, with a count of 0. |
| `days[].date` | `string` (date) | The day, YYYY-MM-DD, as the platform buckets contributions (GitHub: UTC). |
| `days[].level` | `integer` or `null` | The shade the platform paints the day, 0 (no contributions) to 4 (its busiest), as it computes it; null when it shows none. |
| `days[].metrics` | `object` | The day's counts; null = the platform did not say, 0 = none. |
| `days[].metrics.contribution_count` | `integer` or `null` | Contributions that day as the platform counts them (GitHub: commits, issues, pull requests, reviews, and private ones when the account shows them); 0 when none. |
| `metrics` | `object` | The period's totals; null = the platform did not say. |
| `metrics.contribution_count` | `integer` or `null` | Contributions over the whole period, the sum of days\[\].metrics.contribution_count. |
| `platform_specific` | `object` | Fields only this platform has, under its ID (platform_specific.\<platform>); each null when unknown. |
| `platform_specific.github` | `object` or `null` | A GitHub calendar's own fields: its activity overview. |
| `platform_specific.github.commit_percent` | `integer` or `null` | Share of the period's contributions that are commits, 0 to 100, as GitHub's activity overview rounds it; null when the account hides its overview. |
| `platform_specific.github.issue_percent` | `integer` or `null` | Share that are issues opened, 0 to 100; null when the account hides its overview. |
| `platform_specific.github.pull_request_percent` | `integer` or `null` | Share that are pull requests opened, 0 to 100; null when the account hides its overview. |
| `platform_specific.github.code_review_percent` | `integer` or `null` | Share that are pull request reviews, 0 to 100; null when the account hides its overview. |
| `approximate_fields` | `string[]` | JSON paths of values rounded or capped by the platform. \[\] when all exact (every platform's counts are exact today). |
| `unknown_fields` | `string[]` | JSON paths of lists whose \[\] means unknown rather than none; days always lists the period, so always \[\]. |

## Item errors

Besides the [request-level errors](https://socialtap.dev/docs/errors/index.md) every endpoint can return, contribution calendar endpoints return:

| Code | HTTP | Retry | Meaning | What to do |
| --- | --- | --- | --- | --- |
| `not_found` | 404 | No | The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). | Check the link or ID. Do not retry. |
| `private_or_unavailable` | 403 | No | The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. | Only public items can be fetched. Do not retry. |

---

[HTML version](https://socialtap.dev/resources/contribution_calendar/) · [Docs index for AI agents](https://socialtap.dev/llms.txt) · [All docs in one file](https://socialtap.dev/llms-full.txt)
