This note was prepared with AI assistance. Its checks use synthetic Response objects in one Node process, not captured production traffic or requests to a live API.

Four checks, four different jobs

Response.ok is true for HTTP statuses from 200 to 299. It does not inspect whether the response contains the data your screen needs. Source: https://developer.mozilla.org/en-US/docs/Web/API/Response/ok

Content-Type describes the declared media type. A client expecting application/json can reject text/html before attempting to parse a proxy or sign-in page as data. A JSON media type is still a declaration, not proof that its body is valid. Source: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Type

Response.json() reads and parses the body. A malformed body can reject with SyntaxError. Successful parsing also allows arrays, strings and numbers, so it cannot establish an application-specific object shape. Source: https://developer.mozilla.org/en-US/docs/Web/API/Response/json

A deliberately small contract

This helper expects a successful response containing application/json and an object with a nonblank string id. It normalizes the media type before comparison and leaves parse failures visible. The rule belongs to this example endpoint; it is not a universal JSON client.

export async function readRecord(response) {
  if (!response.ok) throw new Error(`http_${response.status}`);
  if (response.status === 204) throw new Error('body_required');
  const mediaType = (response.headers.get('content-type') ?? '')
    .split(';', 1)[0].trim().toLowerCase();
  if (mediaType !== 'application/json') throw new Error('json_expected');
  const value = await response.json();
  if (!value || typeof value !== 'object' || Array.isArray(value) ||
      typeof value.id !== 'string' || value.id.trim() === '') {
    throw new Error('record_expected');
  }
  return value;
}

The executed examples produce distinct outcomes. A 200 HTML response fails with json_expected. A 200 malformed JSON body rejects with SyntaxError. A 200 object containing only message fails with record_expected. A 200 response containing {"id":"sample-1"} is accepted, including when the media type includes a charset parameter. Additional cases cover an array, a blank id, a missing media type, an unsupported JSON-suffixed media type and HTTP 500.

A synthetic 204 response has ok equal to true but fails this helper with body_required. That is intentional for an endpoint whose contract requires a record. Another endpoint can legitimately complete with no response body: 204 means No Content. Such a client should handle that contract explicitly instead of always calling json(). Source: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/204

Keep failures distinguishable

A local API client inspected for this note already rejects successful non-JSON responses, but converts JSON parse failures to an empty object. That fallback illustrates a separate review question: can an empty object be mistaken for valid data? Silencing a parse failure does not establish the expected shape.

The teaching helper accepts only application/json. An API that documents another JSON media type needs a deliberate allowlist or another appropriate media-type rule. The id check is similarly narrow: it does not validate every field, prove that the identifier exists, or establish authorization.

The useful test report records which layer rejected each response. Network failures, aborts, body-size limits and server-side behavior need their own relevant checks. These local cases establish only how the example handles the supplied status, headers, body and minimal shape.

Olzhas Azirali is an app developer in Astana and founder of AZIRAL since 2019.

A report can acquire false precision before it draws its first chart. Replace every empty CSV cell with zero, calculate a rate, and an incomplete observation suddenly looks like a measured result.

A small Python tool makes the problem easy to inspect. The public insights.py helper in AZIRAL's Instagram Agent Skill reads a local CSV and prints a JSON report. It keeps a blank metric separate from an observed zero. The distinction affects both action rates and the sample used for comparisons.

The example below is synthetic. It is a reproducible data-handling exercise, not AZIRAL account performance or a client result.

Start with a data contract

The helper requires two columns: post_id and format. Metrics such as reach, views, saves and shares are optional. A missing metric column represents an unknown observation for every row. A blank cell represents an unknown observation for that row. An explicit 0 records an observed zero.

Those meanings belong in the input contract before any calculation. Missing data could reflect an unavailable export field, an incomplete collection process or another cause. The CSV alone does not establish which explanation applies. Preserving the gap avoids silently choosing one.

For this helper, counts must be finite, nonnegative integers no larger than 9007199254740991. It rejects duplicate post IDs, repeated column names, mismatched row widths and malformed count values. A validation error stops the CLI with a nonzero exit code instead of producing a partial JSON report.

An eight-row example

Save this as synthetic.csv in a checkout of the public repository:

post_id,format,reach,views,saves,shares
r1,reel,1000,1000,0,5
r2,reel,2000,3000,10,
r3,reel,,500,4,0
r4,reel,0,0,2,1
r5,reel,500,,5,2
c1,carousel,100,200,1,0
c2,carousel,100,400,0,
c3,carousel,50,,,1

Run it with Python 3.10 or later:

python3 skills/aziral-instagram-insights/scripts/insights.py synthetic.csv

The helper uses Python's standard library. Its CSV schema assumes one account and comparable observation windows. The rows above are invented for explanation; their combinations exercise validation and calculation rules rather than describe a real account.

Five rows are reels and three are carousels. Some observations are intentionally absent. Row r4 records zero reach and zero views while preserving its other supplied counts. Keeping those raw values does not make a reach-based rate calculable.

Guard the numerator and the denominator

The calculation in the public script has a small, explicit guard:

def ratio(numerator, denominator, scale=1):
    if numerator is None or denominator is None or denominator <= 0:
        return None
    return round(numerator / denominator * scale, 6)

This excerpt omits type annotations for readability; its calculation matches the source. For an action rate, the script passes 1000 as the scale and uses that post's reach as the denominator. These are action counts per 1000 reached accounts, not probabilities of unique-person conversion.

The results show why a single fallback value would lose information:

post   saves per 1000 reach   shares per 1000 reach
r1     0                     5
r2     5                     null
r3     null                  null
r4     null                  null
r5     10                    4

Row r1 has an observed saves count of zero and positive reach, so its saves rate is zero. Row r2 has a valid saves rate but no shares observation. Row r3 has no reach observation. Row r4 has an observed denominator of zero. Both r3 and r4 therefore have unavailable action rates, while their raw metrics retain different states.

In Python, the unavailable result is None. JSON serialization represents it as null. A consumer can display an unavailable marker and retain the reason in the underlying metrics instead of presenting an invented numeric result.

Show how much data supports the summary

The report includes observed_posts counts for each metric. In the reel group, reach is observed for four of five rows. The observed zero in r4 contributes to that coverage count. Views are also observed for four rows; the blank views cell in r5 does not contribute.

Coverage is useful beside a summary because different metrics can have different denominators of available observations. A group containing five posts does not imply five observations for every field. This example also has no comments column, so the observed comments count is zero. That describes data availability, not a measured total of zero comments.

The report retains raw metrics, derived rates, group coverage and warnings together. A reader can trace an unavailable result without guessing what a blank meant earlier in the pipeline.

Keep format comparisons descriptive

The reel views sample is 0, 500, 1000 and 3000. Its median is 750. The missing observation is excluded; the observed zero is included. Row r2 therefore has a views_vs_format_median value of 4.

That number compares the row with the supplied same-format sample. The focal post is included in the median. It is not a comparison with an independently measured account baseline, and it does not explain why a post received its views.

The carousel sample has two observed views values, 200 and 400, producing a median of 300. Its group contains only three posts, so the helper adds a small-sample warning. The five-post threshold is a reporting caution chosen by the tool, not a statistical validation rule. Missing observations also generate warnings.

Publication age, paid distribution and selective exports can still affect comparability. None of those conditions can be reconstructed from these columns. A useful next experiment would define a consistent observation window and change one content variable, while recording the relevant metrics explicitly.

Make number formatting explicit

The parser uses Decimal on stripped input; it does not detect the export's numeric locale. In a direct parser check, the string 1.000 becomes the integer 1. The string 1,000 is rejected. A quoted CSV field can preserve a comma inside the cell, but that does not turn it into an accepted numeric grouping convention.

The sample deliberately uses unformatted integers. If a source uses decimal commas or grouping separators, establish that source's convention before normalizing it. Silent punctuation removal could change the value. Validation and a documented export format work together here.

A small rule with a visible consequence

Keeping unknown values distinct from zero makes the report easier to audit. The output can state which values were observed, which calculations were possible and what sample supported a comparison.

The source and usage instructions are public: https://github.com/azirali/instagram-agent-skill/tree/main/skills/aziral-instagram-insights

About the author and other AZIRAL products: https://aziral.com/en/olzhas-azirali

Prepared with AI assistance from the public source code. The eight-row example and the parser cases described here were reproduced locally with Python 3.14.7. They demonstrate implementation behavior, not audience growth or a forecast.