# PyTorch HUD API Data Structure Documentation
This document outlines the structure of data returned by the PyTorch HUD API.
## Top Level Structure
The PyTorch HUD API returns a JSON object with the following top-level fields:
```json
{
"shaGrid": [], // Array of commit objects
"jobNames": [] // Array of job name strings
}
```
- `shaGrid`: Array of commit objects, each representing a single commit with all its jobs
- `jobNames`: Array of job name strings, used for job name reference
## Pagination
The `per_page` parameter controls how many commits are returned in the `shaGrid` array:
- `per_page=1`: Returns only the specified commit
- `per_page=N`: Returns the specified commit plus N-1 previous commits
## Commit Object Structure
Each commit object in the `shaGrid` array has the following structure:
```json
{
"author": "string", // GitHub username of the commit author
"authorUrl": "string", // GitHub URL for the author
"time": "string", // ISO timestamp of the commit
"sha": "string", // Full commit SHA
"commitUrl": "string", // GitHub URL to the commit
"commitTitle": "string", // First line of the commit message
"commitMessageBody": "string", // Rest of the commit message
"prNum": number, // PR number (if applicable)
"diffNum": null, // Differential number (if applicable)
"jobs": [], // Array of job objects
"isForcedMerge": boolean, // Whether commit was force-merged
"isForcedMergeWithFailures": boolean // Whether commit was force-merged despite failures
}
```
## Job Object Structure
Each job object has the following structure:
```json
{
"id": number, // Job ID (numeric)
"name": "string", // Job name
"conclusion": "string", // Job status: "success", "failure", "pending", "skipped", "queued"
"workflowName": "string", // Name of the workflow this job belongs to
"url": "string", // URL to view job details
"duration": number, // Job duration in seconds
"failureLines": [ // Array of failure message lines (only present for failures)
"string",
"string",
...
]
}
```
Common job status values:
- `success`: Job completed successfully
- `failure`: Job failed
- `pending`: Job is running
- `skipped`: Job was skipped
- `queued`: Job is waiting to start
## Usage Examples
### Iterating Through Commits
```python
data = api.get_hud_data("pytorch", "pytorch", COMMIT_SHA, per_page=5)
for commit in data["shaGrid"]:
print(f"Commit SHA: {commit['sha']}")
print(f"Author: {commit['author']}")
print(f"PR: {commit['prNum']}")
```
### Analyzing Jobs for a Commit
```python
commit = data["shaGrid"][0] # Get the first commit in the response
jobs = commit["jobs"]
# Count jobs by status
status_counts = {}
for job in jobs:
status = job.get("conclusion", "pending")
status_counts[status] = status_counts.get(status, 0) + 1
# Find failing jobs
failing_jobs = [job for job in jobs if job.get("conclusion") == "failure"]
for job in failing_jobs:
print(f"Failed job: {job.get('name')}")
if "failureLines" in job:
print(f"Failure reason: {job['failureLines'][0]}")
```
## Notes
1. Job IDs are numeric and should be used as integers when making API calls to get job details.
2. When using `per_page=1`, you get only the requested commit.
3. Failure information is only included for jobs that have failed.
4. Some job entries might be missing certain fields depending on their status.