API Weekly Report Example

4 min readLast updated View as MarkdownAgent setup

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:read and recommendations: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.

  1. 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"
  2. List the projects. Copy an id into PROJECT_ID.

    curl -s "https://api.apptonomy.ai/v1/projects?limit=25" \
      -H "Authorization: Bearer $APPTONOMY_API_KEY"
  3. Read the latest completed audit. Copy its id into AUDIT_ID.

    curl -s "https://api.apptonomy.ai/v1/projects/$PROJECT_ID/audits?status=completed&limit=1" \
      -H "Authorization: Bearer $APPTONOMY_API_KEY"
  4. Read the two most recent scores. When pagination.hasMore is true, copy pagination.nextCursor into CURSOR.

    curl -s "https://api.apptonomy.ai/v1/projects/$PROJECT_ID/scores?limit=2" \
      -H "Authorization: Bearer $APPTONOMY_API_KEY"
  5. 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"
  6. List the audit’s open recommendations. Copy one id into RECOMMENDATION_ID.

    curl -s "https://api.apptonomy.ai/v1/projects/$PROJECT_ID/recommendations?auditId=$AUDIT_ID&status=open" \
      -H "Authorization: Bearer $APPTONOMY_API_KEY"
  7. 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"
  8. Without the Authorization header the API answers 401 unauthenticated.

    curl -s https://api.apptonomy.ai/v1/organization
  9. A parameter out of range answers 400 invalid_request, and details names 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 needs analytics:read).
  • Generate a client from the OpenAPI document.
  • Handle limits: read the RateLimit header and wait for Retry-After on a 429 — see Rate limits and quotas.
  • Every resource and filter: Resources; every error: Conventions.