We're excited to announce one of our most frequently requested features, the ability to use our API to extract data rendered in our site's charts, is now live!


The Reports API gives you the ability to get an exact equivalent to our timeline-based area charts, such as those you'd see on our Velocity reports page. If you have any sort of use case that requires pulling this data down and treating it in a specific way, you're likely already doing so via individual CSV downloads. This new API functionality allows you to accomplish the same thing, dramatically faster, and to fetch data programmatically.


linkExample 1: Grabbing a basic velocity report


To get a sample of how to use this functionality to get a simple, timeline-based view of recent Diff Delta in your repo, you can run this simple curl, with appropriate values substituted for your API token and resource path (which can just be your entity slug - the part that appears directly after entities/ and before the next slash in the URL) to one of your reports:


curl -H "Authorization: Bearer YOUR_API_TOKEN" "https://www.gitclear.com/api/v1/reports?resource_path=YOUR_ENTITY_SLUG&team_slug=all-contributors&days_ago=30"


(This request uses your entity's default team, all-contributors, but you can use any team you happen to be a member of)


This will request the past 30 days of Diff Delta data within your entity. You should see a result that looks something like this (truncated for simplicity):


{ "context": { "entity": "YOUR_ENTITY_SLUG" "team": "all-contributors" }, "interval_em": "daily", "series_segments": { "Diff Delta": [ { "url": "https://www.gitclear.com/entities/YOUR_ENTITY_SLUG/teams/all-contributors/commits?end_date=2022-10-08", "x": "October 8", "y": 467.62 }, { "url": "https://www.gitclear.com/entities/YOUR_ENTITY_SLUG/teams/all-contributors/commits?end_date=2022-10-09", "x": "October 9", "y": 427.96 }, { "url": "https://www.gitclear.com/entities/YOUR_ENTITY_SLUG/teams/all-contributors/commits?end_date=2022-10-10", "x": "October 10", "y": 323.01 } } ], "unit": "Diff Delta" }


You'll see here that we list the interval of data points, the unit that the results are presented in, and a set of X/Y data points, with the X values being dates and the Y values being the Diff Delta on that particular date. Each data point also includes a URL that points back to commits on that particular date, as represented on our Commit Activity Browser.


In case resource_path isn't familiar to you, this the path to the specific resource you want to target. You may target a specific entity (e.g. some-entity), an organization within an entity (some-entity/some-org) or a repo in an organization (some-entity/some-org/some-repo). It will the immediate chunks of the URL after some-entity on one of your pages.


linkExample 2: Velocity segmented by ticket type


The key parameter that you'll want to use to generate different types of data is segment_by, which changes the graph segmentation, or, put simply: What type of data you are grabbing. There are a set of values you can give to segment_by that are more thoroughly documented on our API documentation , but for a simple exercise, we can select ticket_type, which breaks everything down by the particular ticket category in Jira (e.g. New feature, bug...). We'll also change our days_ago to 90, giving us a broader data set:


curl -H "Authorization: Bearer YOUR_API_TOKEN" "https://www.gitclear.com/api/v1/reports?resource_path=YOUR_ENTITY_SLUG&team_slug=all-contributors&days_ago=90&segment_by=ticket_type"


Translates to this result:


{ "context": { "entity": "YOUR_ENTITY_SLUG", "team": "all-contributors" }, "interval_em": "weekly", "series_segments": { "No Issue": [ { "url": "https://www.gitclear.com/entities/YOUR_ENTITY_SLUG/teams/all-contributors/commits?end_date=2022-09-26", "x": "September 26", "y": 5982.0 }, { "url": "https://www.gitclear.com/entities/YOUR_ENTITY_SLUG/teams/all-contributors/commits?end_date=2022-10-03", "x": "October 3", "y": 4254.0 }, { "url": "https://www.gitclear.com/entities/YOUR_ENTITY_SLUG/teams/all-contributors/commits?end_date=2022-10-10", "x": "October 10", "y": 703.0 } ], "Task": [ { "url": "https://www.gitclear.com/entities/YOUR_ENTITY_SLUG/teams/all-contributors/commits?end_date=2022-09-26", "x": "September 26", "y": 976.0 }, { "url": "https://www.gitclear.com/entities/YOUR_ENTITY_SLUG/teams/all-contributors/commits?end_date=2022-10-03", "x": "October 3", "y": 3161.0 }, { "url": "https://www.gitclear.com/entities/YOUR_ENTITY_SLUG/teams/all-contributors/commits?end_date=2022-10-10", "x": "October 10", "y": 535.0 } ], "New Feature": [ { "url": "https://www.gitclear.com/entities/YOUR_ENTITY_SLUG/teams/all-contributors/commits?end_date=2022-09-26", "x": "September 26", "y": 590.0 }, { "url": "https://www.gitclear.com/entities/YOUR_ENTITY_SLUG/teams/all-contributors/commits?end_date=2022-10-03", "x": "October 3", "y": 1.0 }, { "url": "https://www.gitclear.com/entities/YOUR_ENTITY_SLUG/teams/all-contributors/commits?end_date=2022-10-10", "x": "October 10", "y": 44.0 } ] }, "unit": "Diff Delta" }


A few things may jump out to you about this: The data points on the X axis are now shown in weekly installments (on each Monday), given the longer timeframe. Time spans beyond a month are automatically segmented weekly, rather than daily, and ones that are beyond a year will segment by month, rather than by week.


You may also notice the fact that the series segments are now much more descriptive - in this case, each segment has its own name that matches the particular issue type at that time. Hence, you can see how each issue type's Diff Delta has trended at each data point.


linkExample 3: Grabbing summarized stats


One thing that you can optionally pass is calculate_summary_stats=true, which will render a set of high-level stats that compliment the particular segmentation given, similar to the summary stat boxes below the top chart on the Velocity reports page. Here, we'll do that, and segment by our entity's PR cycle time:


curl -H "Authorization: Bearer YOUR_API_TOKEN" "https://www.gitclear.com/api/v1/reports?resource_path=YOUR_ENTITY_SLUG&team_slug=all-contributors&days_ago=90&segment_by=pr_cycle&generate_summary_stats=true"


Which will generate this example output:


{ "context": { "entity": "YOUR_ENTITY_SLUG", "team": "all-contributors" }, "interval_em": "weekly", "series_segments": { "toolkit-mobile": [ { "url": "https://www.gitclear.com/entities/YOUR_ENTITY_SLUG/teams/all-contributors/commits?end_date=2022-09-26", "x": "September 26", "y": 5.0 }, { "url": "https://www.gitclear.com/entities/YOUR_ENTITY_SLUG/teams/all-contributors/commits?end_date=2022-10-03", "x": "October 3", "y": 18.0 }, { "url": "https://www.gitclear.com/entities/YOUR_ENTITY_SLUG/teams/all-contributors/commits?end_date=2022-10-10", "x": "October 10", "y": 6.0 } ], "frontend-stats": [ { "url": "https://www.gitclear.com/entities/YOUR_ENTITY_SLUG/teams/all-contributors/commits?end_date=2022-09-26", "x": "September 26", "y": 12.0 }, { "url": "https://www.gitclear.com/entities/YOUR_ENTITY_SLUG/teams/all-contributors/commits?end_date=2022-10-03", "x": "October 3", "y": 5.0 }, { "url": "https://www.gitclear.com/entities/YOUR_ENTITY_SLUG/teams/all-contributors/commits?end_date=2022-10-10", "x": "October 10", "y": 1.0 } ] }, "unit": "Days", "calculated_summary_stats": { "interval_em": "weekly", "cycle_time_per_pr": { "percent_change": "-44%", "previous_period_sum": "4.7 weekdays", "subtext": "per pull request", "sum_total": "8.5 weekdays", "tooltip_text": "Among 61 pull requests closed during the current period, the \naverage pull request spent 8.5 weekdays between the time for pull requests to move from first commit to merged. \nDuring the previous period of the same length, 4.7 weekdays was \n averaged among the 45 pull requests closed.\n Thus, the time for pull requests to move from first commit to merged 44% slower during this period than the previous period.\n" }, "delta_per_pr": { "diminished": true, "sum_total": 758, "previous_period_sum": 1039, "tooltip_text": "758 Diff Delta per open pull request was observed during this period. \nDuring the previous period of the same length, 1039 Diff Delta per pull requests was averaged.\n" }, "pr_posted_count": { "diminished": false, "per_weekday": 1.6, "previous_per_weekday": 1.2, "percent_change": 32, "previous_period_sum": 79, "sum_total": 104, "tooltip_text": "During this period, beginning on July 12, 2022 and spanning 64 weekdays, 1.6 pull requests were posted per weekday over this period. \nDuring the previous period of the same length, 1.2 pull requests were posted per weekday.\n", "percent_change_text": "+32%" }, "calculated_stats": "calculated_pull_requests", "days_active": 90 } }


You'll notice that unit here is now days (as one would expect for looking at PR cycle time), and we now have a series of new keys added to our JSON response, which describe various high-level stats, including whether or not they have diminished (have a negative trend line) in the current time frame relative to the previous. In addition, as is the case for PR cycle time, data is now segmented repo-by-repo.


linkExample 4: Grabbing recent Diff Delta velocity for a specific contributor


One final method of digging through data is to grab stats for a particular individual contributor, which we can do by specifying a committer_user_name (matching the username given in the URL when you visit a stats page for that contributor). Using this request:


curl -H "Authorization: Bearer YOUR_API_TOKEN" "https://www.gitclear.com/api/v1/reports?resource_path=YOUR_ENTITY_SLUG&team_slug=all-contributors&days_ago=90&committer_user_name=YOUR_CONTRIBUTOR"


We get a result like this, with Diff Delta for that individual contributor:


{ "context": { "committer": "YOUR_CONTRIBUTOR", "entity": "YOUR_ENTITY_SLUG", "team": "all-contributors" }, "interval_em": "weekly", "series_segments": { "Diff Delta": [ { "url": "https://www.gitclear.com/entities/YOUR_ENTITY_SLUG/teams/all-contributors/commits?end_date=2022-09-26", "x": "September 26", "y": 832.09 }, { "url": "https://www.gitclear.com/entities/YOUR_ENTITY_SLUG/teams/all-contributors/commits?end_date=2022-10-03", "x": "October 3", "y": 858.39 }, { "url": "https://www.gitclear.com/entities/YOUR_ENTITY_SLUG/teams/all-contributors/commits?end_date=2022-10-10", "x": "October 10", "y": 147.0 } ] }, "unit": "Diff Delta" }


That's it! From here, you should be able to grab all sorts of interesting stats from your GitClear data. You can see full details on this endpoint from our API reference. If you have any questions, or need help using some particular aspect of this new reports API, leave a comment here or contact support@gitclear.com.