Expand responses

Endpoints return a useful default shape. Anything expensive, verbose, or usually unwanted is opt-in through an include_ parameter.


curl -G https://api.askylabs.com/v1/brands/b_7a3f.../responses \
  -H "Authorization: Bearer $ASKY_API_KEY" \
  -d limit=5 \
  -d include_full_response=true

Every include_ parameter is a boolean, defaults to false, and is documented on the endpoint that accepts it.

Two kinds of include

They share a prefix but do different things, and the distinction matters when you are reasoning about result counts.

Field expansion adds data to rows you were already getting. The row count is unchanged; the rows get bigger.

Row inclusion widens the result set with rows that are hidden by default. The shape is unchanged; you get more rows.

Parameter	Kind	Effect
`include_full_response`	Field	Returns the complete AI answer instead of `response_snippet`
`include_citation_rate`	Field	Adds a per-point brand citation rate to a time series
`include_citations`	Field	Adds the citations attached to each row
`include_statistics`	Field	Adds computed statistics to each row
`include_internal_links`	Field	Adds internal link data to page rows
`include_translations`	Row	Includes translated child articles, hidden by default
`include_snoozed`	Row	Includes tasks snoozed into the future, hidden by default
`include_competitor_owned_domains`	Row	Includes domains owned by tracked competitors

If a result count changes when you toggle an include, you used a row-inclusion parameter. That is expected behaviour, not a filtering bug.

Why they default to off

Three reasons, and each one has a practical consequence for your integration.

Response size. A full AI answer is often several kilobytes. Twenty of them turn a compact page into a payload that is slow to transfer and slow to parse, for data most callers never read.

Latency. Expansions cost work on our side. A request that returns snippets answers quickly; one that assembles full text and citations does not.

Rate limit budget. Some expansions cap the page size, so asking for more per row means more requests overall. include_full_response requires limit of 5 or less. Pulling 1,000 responses with full text is 200 requests rather than 10, which is a meaningful share of your per-minute budget.

The pattern that works: walk the list cheaply, decide which rows you actually need in full, then fetch those specifically.

Expansions respect your scopes

An expansion that crosses into another area of your data requires the scope for that area.

include_citation_rate on a visibility series needs read:citations, because a citation rate is citation data. If your key lacks it, the request still succeeds. The series is omitted and named in omitted_for_scope:


{
  "data": {
    "series": [ ... ],
    "omitted_for_scope": ["citation_rate"]
  },
  "request_id": "req_01J8Z3KE19"
}

This is deliberate: a missing scope degrades one part of a response rather than failing the whole request, and omitted_for_scope tells you exactly what is absent and why, so absence is never ambiguous. Check it if you are building against a key whose scopes you do not control.

There is no generic expand parameter

Some APIs return nested objects as identifiers and offer a single expand[] parameter to inline them. Asky does not, because our data does not have that shape.

Related data lives at sub-resource paths instead:


GET /v1/brands/{brand_id}/prompts/{prompt_id}
GET /v1/brands/{brand_id}/prompts/{prompt_id}/executions
GET /v1/brands/{brand_id}/prompts/{prompt_id}/citations

Each returns a predictable shape and paginates independently. A generic expansion parameter would make the response shape combinatorial, which makes client types harder to write and makes the OpenAPI specification far less useful for generating them.

Choosing between an include and a sub-resource

Use an include when you want the extra data for most rows in a page. One request beats one request per row.

Use a sub-resource when you want the extra data for a few specific rows, or when you need to paginate it. A prompt can have far more executions than fit alongside a page of prompts, so executions are their own endpoint rather than an expansion.