Response views and paging

01

The three view parameters

response_limit only trims what is shown. To ask the source for fewer items, use its own parameter, such as limit on X's user posts. A response_limit outside the range is moved to the nearest bound, and a response_format that is not one of the three falls back to the default. A view says so in its notes, as it does for a requested field that is not in the response.

02

Which format you get

• A call through a grouped data tool, such as data_x_users, returns markdown.
• A call by per-operation name, such as data_x_user_s_tweets_get_user_tweets, returns raw, the payload exactly as it always was. Pass response_format to get a view.
• The data tools listed under their own names, data_web_scrape, data_web_search, data_web_map and data_agnt_people_find_mobile, are per-operation names, so they return raw too.
• Over REST, a request returns raw unless it carries a view parameter.
• Where the default is raw, passing response_fields or response_limit without a format returns json.
• raw ignores response_fields and response_limit. Over REST and on grouped calls, meta.view.warnings says so.

Grouped data tools list the three parameters in their input schema. Per-operation data tools accept them without listing them, so their definitions stay unchanged. Which tools are grouped is on Grouped tools.

03

Markdown

A list comes back as a table of the view's default columns, leaving out any column no row fills. A single item comes back as key: value lines, and a field it shows that has no value reads key: (empty), so a profile with no bio never looks like a view with no bio field.

{
  "name": "data_x_users",
  "arguments": { "action": "tweets", "username": "superagnt", "response_limit": 3 }
}

| post_id | created_at | text | likes | reposts | replies | views |
| --- | --- | --- | --- | --- | --- | --- |
| 1971000000000000003 | Tue Sep 29 16:02:11 +0000 2026 | Grouped tools are live. | 412 | 38 | 21 | 90211 |
| 1971000000000000002 | Mon Sep 28 18:40:07 +0000 2026 | One tool per resource, one action per operation. | 97 | 12 | 4 | 20877 |
| 1971000000000000001 | Mon Sep 28 09:15:52 +0000 2026 | Shipping notes for this week. | 55 | 9 | 3 | 14010 |

3 of 20 posts on this page · next: continuation_token=DAAHCgABGrfCx2___-sLAAIAAAATMTkyNTA0 · cost 0.5¢

The footer says how many items are shown: out of the upstream total when the source reports one (25 of 1240 people), out of the page when you cut the list yourself (3 of 20 posts on this page). It then names the parameter and value that fetch the next page, and the cost of the call.

Anything to read before the rows comes first, one line each: an empty result's notice (No results matched this query. You were not charged.), a warning the source attaches to the result (Warning: ...), arguments the grouped tool dropped (Ignored args (not used by this action): ...), and notes such as Note: Not found in this response: ... for a requested field that is not there.

Table cells are kept short: line breaks are removed and a cell is cut at 200 characters, or 2,048 for a URL. Decimals are rounded to two places, or three significant digits below 1. A view field that names a point in time, such as created_at, is shown as ISO 8601 UTC when the source sends it as epoch seconds or milliseconds, in markdown and in JSON. Use json or raw when you need the whole text or the exact number.

04

JSON

json returns { "items": [...], "next": {...}, "total": ... } for a list and the item itself for a single result. Its values are not cut or rounded the way table cells are. next holds param and value, plus with when the next page needs more than one parameter, and tool when a different tool takes it (see Paging below). total is there when the source reports one.

Notes ride in the JSON too, beside items: notice (an empty result's notice), warning (the source's warning), notes (for example a requested field that was not found) and ignored_args. A single item with a note is wrapped as { "item": ... } with the note beside it:

{ "notes": ["Not found in this response: follower_total."], "item": { "username": "superagnt", "followers": 12840 } }

05

Curated and generic views

Every data operation has a view. Most have a curated one that picks the fields worth reading under stable names: an X post's text, likes, reposts and views, an X account's username, followers and bio. Any other payload gets the generic view, which unwraps common envelopes, picks the main list, drops empty and noisy keys, cuts long strings at 280 characters, and cuts nested lists at 10 entries with a note saying so.

When a response does not have the shape its curated view expects, the result says so and shows the generic view instead. If shaping fails altogether, you get the raw payload. Use raw whenever you need a field a view leaves out, or name the field in response_fields, which reads it from the raw item.

06

Size cap

Markdown and JSON output are capped at 24,000 characters, and lower for an agent on superagnt_'s own runtime, whose tool results are shorter. A capped list drops whole rows and says how many it shows. A capped single item cuts its text in markdown, or its longest strings in JSON. The note says how to narrow it: response_fields for fewer fields, response_limit for fewer items on a list, or raw. truncated is true in the view metadata. The view never caps raw output.

07

Over MCP

A markdown or json result is one text content block, with no structuredContent. The call's metadata, such as costCents, rides in _meta["agnt/meta"], and its view object describes the output: format, view (spec for a curated view, generic, or raw), entity, returned, page_items, total, next, fields and cost_cents, plus guidance (the source's warning), ignored_args, truncated and warnings when they apply. Clients generally do not show _meta to the model, which is why the markdown head and footer, and the JSON notes, carry what the model needs.

A raw result keeps its usual shape: the pretty-printed payload as text, plus structuredContent with data and meta. On a grouped call that passed a view parameter or had arguments dropped, meta.view reports what was read.

08

Paging

Each page is a separate call, billed on its own. Send page tokens back exactly as they came.

Grouped tools: call the same action again

Many X and YouTube operations, and TikTok's user videos, page through a separate next-page operation with a continuation_token. On a grouped tool, call the same action again with the token from the previous result:

{
  "name": "data_x_users",
  "arguments": {
    "action": "tweets",
    "username": "superagnt",
    "continuation_token": "DAAHCgABGrfCx2___-sLAAIAAAATMTkyNTA0"
  }
}

The call goes to the next-page operation (here data_x_user_s_tweets_continuation_get_user_tweets_continuation), so next-page operations are not listed as actions of their own. They stay callable by their per-operation names. The grouped tool's description says which actions page this way, in a Next page: line.

Some next pages need more than the token. TikTok's user_videos pages with continuation_token, secondary_id and username together, all printed on the previous result's next line (next: continuation_token=...; secondary_id=...; username=...). The call goes to the next-page operation only when continuation_token and secondary_id are both there. Without secondary_id it fetches the first page again, and the token shows up in ignored_args.

Per-operation names

A first-page tool called by its per-operation name does not take continuation_token: its next page is the separate next-page tool. When you ask such a call for a view, next names that tool in next.tool, and the footer reads next: call data_x_user_s_tweets_continuation_get_user_tweets_continuation with continuation_token=....

Sources with their own paging parameters

Other sources page with their own parameters, such as Reddit's cursor, Instagram's max_id, end_cursor or page, Facebook's end_cursor and LinkedIn's paginationToken. Those are ordinary arguments of the operation: pass them to the same action. The footer and next name the exact parameter and value to send.

Some LinkedIn feeds need an offset, start or page, moved forward along with paginationToken, and the response does not say where this page started. Those results have no next. A note at the top says what to send instead:

Note: Next page: call again with both paginationToken=<token> and start set to this call's start plus 50 (start=50 for page 2, 100 for page 3).

09

Over REST

The same three parameters work as query parameters on the data REST routes, /v1/data/:source/* and /v1/data/agnt/*. Every /v1/data/agnt/* route is a POST: put the view parameters in the query string, not the body.

curl -G "https://api.superagnt.com/v1/data/x/user/tweets" \
  -H "Authorization: Bearer $AGNTDATA_API_KEY" \
  --data-urlencode "username=superagnt" \
  --data-urlencode "response_format=json" \
  --data-urlencode "response_fields=post_id,text,likes" \
  --data-urlencode "response_limit=2"

A request with no view parameter gets exactly the response it always did. With one, data is the markdown text or the JSON view, and meta keeps its usual keys plus view:

{
  "success": true,
  "data": {
    "items": [
      { "post_id": "1971000000000000003", "text": "Grouped tools are live.", "likes": 412 },
      { "post_id": "1971000000000000002", "text": "One tool per resource, one action per operation.", "likes": 97 }
    ],
    "next": { "param": "continuation_token", "value": "DAAHCgABGrfCx2___-sLAAIAAAATMTkyNTA0" }
  },
  "meta": {
    "costCents": 0.5,
    "purchasedBalanceCents": 944,
    "subscriptionRemainingCents": 500,
    "cached": false,
    "latencyMs": 812,
    "view": {
      "format": "json",
      "view": "spec",
      "entity": "post",
      "returned": 2,
      "page_items": 20,
      "next": { "param": "continuation_token", "value": "DAAHCgABGrfCx2___-sLAAIAAAATMTkyNTA0" },
      "fields": ["post_id", "text", "likes"],
      "cost_cents": 0.5
    }
  }
}

An explicit response_format=raw keeps the raw data and adds meta.view, which then only reports what was read. response_fields can also be repeated (?response_fields=text&response_fields=likes).

curl -X POST "https://api.superagnt.com/v1/data/agnt/people/search?response_format=markdown&response_limit=10" \
  -H "Authorization: Bearer $AGNTDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "filters": { "person_job_title": { "include": ["VP of Sales"] } }, "page": 1 }'

To page over REST, call the operation's next-page route with the token. For X posts that is /v1/data/x/user/tweets/continuation:

curl -G "https://api.superagnt.com/v1/data/x/user/tweets/continuation" \
  -H "Authorization: Bearer $AGNTDATA_API_KEY" \
  --data-urlencode "username=superagnt" \
  --data-urlencode "continuation_token=DAAHCgABGrfCx2___-sLAAIAAAATMTkyNTA0" \
  --data-urlencode "response_format=markdown"

10

Related

• Data sources: making a data call, prices and errors.
• Grouped tools: how data tools are grouped and how a grouped call is routed.
• API reference: every data operation with its parameters and price.