---
title: API Weekly Report Example
description: Make your first Public API requests with curl, then run a weekly ASO report in JavaScript that follows pagination and handles errors.
---

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](/docs/api/keys) 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:

```bash
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.

   ```bash
   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`.

   ```bash
   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`.

   ```bash
   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`.

   ```bash
   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.

   ```bash
   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`.

   ```bash
   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.

   ```bash
   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`.

   ```bash
   curl -s https://api.apptonomy.ai/v1/organization
   ```

9. A parameter out of range answers 400 `invalid_request`, and `details` names the parameter.

   ```bash
   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.

```js
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](https://api.apptonomy.ai/v1/openapi.json).
- **Handle limits**: read the `RateLimit` header and wait for `Retry-After` on a `429` — see [Rate limits and quotas](/docs/api/conventions#rate-limits-and-quotas).
- Every resource and filter: [Resources](/docs/api/resources); every error: [Conventions](/docs/api/conventions#errors).
