API Weekly Report Example
This walkthrough reads the data behind a weekly ASO report: your projects, each one’s latest audit and score trend, and the open recommendations with the evidence behind them. It takes a few minutes and needs only a terminal. Every example on this page is run against the API contract in Apptonomy’s CI, so it matches what the API answers.
Before you start
- An API key with at least
organization:read,projects:read,audits:read,scores:readandrecommendations:read. Creating one needs an Owner or Manager and a plan with API access. - At least one project with a completed audit.
Put the key in an environment variable rather than pasting it into commands, so it doesn’t end up in your shell history:
read -rs APPTONOMY_API_KEY && export APPTONOMY_API_KEY
Paste the key and press Enter (nothing is echoed). In CI, set APPTONOMY_API_KEY from your pipeline’s secret store instead.
With curl
Each step reads an id from the previous answer: export it as the variable the step names (export PROJECT_ID=…). Responses print as raw JSON; add | jq to format them.
-
Check the key works: read the organization it belongs to.
curl -s https://api.apptonomy.ai/v1/organization \ -H "Authorization: Bearer $APPTONOMY_API_KEY" \ -H "Accept: application/json" -
List the projects. Copy an
idintoPROJECT_ID.curl -s "https://api.apptonomy.ai/v1/projects?limit=25" \ -H "Authorization: Bearer $APPTONOMY_API_KEY" -
Read the latest completed audit. Copy its
idintoAUDIT_ID.curl -s "https://api.apptonomy.ai/v1/projects/$PROJECT_ID/audits?status=completed&limit=1" \ -H "Authorization: Bearer $APPTONOMY_API_KEY" -
Read the two most recent scores. When
pagination.hasMoreis true, copypagination.nextCursorintoCURSOR.curl -s "https://api.apptonomy.ai/v1/projects/$PROJECT_ID/scores?limit=2" \ -H "Authorization: Bearer $APPTONOMY_API_KEY" -
Fetch the next page with the same query and the cursor.
curl -s "https://api.apptonomy.ai/v1/projects/$PROJECT_ID/scores?limit=2&cursor=$CURSOR" \ -H "Authorization: Bearer $APPTONOMY_API_KEY" -
List the audit’s open recommendations. Copy one
idintoRECOMMENDATION_ID.curl -s "https://api.apptonomy.ai/v1/projects/$PROJECT_ID/recommendations?auditId=$AUDIT_ID&status=open" \ -H "Authorization: Bearer $APPTONOMY_API_KEY" -
Read one recommendation with its provenance: the evidence behind it and where it came from.
curl -s https://api.apptonomy.ai/v1/recommendations/$RECOMMENDATION_ID \ -H "Authorization: Bearer $APPTONOMY_API_KEY" -
Without the
Authorizationheader the API answers 401unauthenticated.curl -s https://api.apptonomy.ai/v1/organization -
A parameter out of range answers 400
invalid_request, anddetailsnames the parameter.curl -s "https://api.apptonomy.ai/v1/projects?limit=500" \ -H "Authorization: Bearer $APPTONOMY_API_KEY"
Every response carries meta.requestId. Keep it when something looks wrong: it is what support needs to find the request.
In JavaScript
The same report as a script, for Node 18 or later with no dependencies. It follows nextCursor until hasMore is false, and turns any refusal into an error naming its status, code and request id. Save it as weekly-report.mjs and run node weekly-report.mjs with APPTONOMY_API_KEY set.
const API = 'https://api.apptonomy.ai/v1';
const KEY = process.env.APPTONOMY_API_KEY; // never hard-code the key
async function get(path) {
const response = await fetch(API + path, {
headers: { Authorization: 'Bearer ' + KEY, Accept: 'application/json' },
});
const body = await response.json();
if (!response.ok) {
const { code, message, requestId, retryable } = body.error;
const retryAfter = response.headers.get('Retry-After');
const error = new Error(response.status + ' ' + code + ': ' + message + ' (request ' + requestId + ')');
error.code = code;
error.retryAfterSeconds = retryable && retryAfter ? Number(retryAfter) : null;
throw error;
}
return body;
}
// Every item of a list, following nextCursor with the same query.
async function listAll(path) {
const items = [];
let cursor = null;
do {
const separator = path.includes('?') ? '&' : '?';
const page = await get(cursor ? path + separator + 'cursor=' + encodeURIComponent(cursor) : path);
items.push(...page.data);
cursor = page.pagination.hasMore ? page.pagination.nextCursor : null;
} while (cursor);
return items;
}
const { data: organization } = await get('/organization');
console.log('Weekly ASO report for ' + organization.name);
for (const project of await listAll('/projects?limit=100')) {
const { data: audits } = await get('/projects/' + project.id + '/audits?status=completed&limit=1');
if (audits.length === 0) {
console.log(project.name + ': no completed audit yet');
continue;
}
const audit = audits[0];
const { data: scores } = await get('/projects/' + project.id + '/scores?limit=2');
const trend = scores.length === 2 ? scores[0].overall - scores[1].overall : null;
const open = await listAll('/projects/' + project.id + '/recommendations?auditId=' + audit.id + '&status=open');
console.log(
project.name + ': score ' + audit.overallScore +
(trend === null ? '' : ' (' + (trend >= 0 ? '+' : '') + trend + ' since the previous audit)') +
', ' + open.length + (open.length === 1 ? ' open recommendation' : ' open recommendations')
);
for (const recommendation of open.filter((r) => r.priority === 'high')) {
console.log(' [high] ' + recommendation.title);
}
}
For an organization with one project, it prints:
Weekly ASO report for EduTravel Games
EduTravel Kids: score 71 (+3 since the previous audit), 1 open recommendation
[high] Replace "travel" in the subtitle with "geography"
Next steps
- Did a listing change work? List published revisions (
/projects/{id}/revisions?status=published&limit=1), then their measured impact (/projects/{id}/impact-results?revisionId=…), then the daily store numbers behind it (/projects/{id}/store-analytics?from=…&to=…, which needsanalytics:read). - Generate a client from the OpenAPI document.
- Handle limits: read the
RateLimitheader and wait forRetry-Afteron a429— see Rate limits and quotas. - Every resource and filter: Resources; every error: Conventions.