TypeScript SDK Live Data

What Live Data Is

Most SDK methods read from the Xpoz database, topping up from the crawler when results look stale. The instagramLive namespace is different: it bypasses the database entirely and fetches straight from the crawler API, so every call returns what Instagram is serving right now. That trade-off is deliberate:

	`client.instagram`	`client.instagramLive`
Source	Database, topped up on demand	Crawler API only
Freshness	May be minutes to days old	Current
Speed	Fast (indexed reads)	Slower (live fetch per call)
Pagination	Page numbers, totals, CSV export	Cursor only
Trial access	Yes	No

Reach for instagramLive when freshness matters more than latency — checking a post’s engagement right now, or pulling a follower list that changed this morning. For analysis over large historical sets, the database-backed methods are faster and support CSV export.

Live methods require a paid account. They always trigger a live fetch, so they are not available on trial access and throw AuthenticationError (HTTP 403).

No connect() Required

Live methods talk to the Xpoz REST API rather than the MCP server, so they work without opening an MCP session:

import { XpozClient } from "@xpoz/xpoz";

const client = new XpozClient({ apiKey: "your-api-key" });

// No await client.connect() needed for live methods
const page = await client.instagramLive.searchPosts("travel");

You still need connect() before using any other namespace (client.instagram, client.twitter, and so on).

CursorResult

Live methods return a CursorResult<T> rather than the PaginatedResult<T> used elsewhere. The upstream API pages with an opaque cursor and reports no totals, so there is no page number, no totalPages, and no getPage(n).

const page = await client.instagramLive.searchPosts("travel", { fields: ["id", "caption"] });

page.data;            // InstagramPost[] — this page
page.hasMore;         // another page is available upstream
page.nextPageCursor;  // opaque token for the next call
page.hasNextPage();   // boolean

Navigating Pages

const page = await client.instagramLive.searchPosts("travel");

// One page at a time
if (page.hasNextPage()) {
  const next = await page.nextPage();
}

// Or walk every page
for await (const post of page.items()) {
  console.log(post.id);
}

// Or page by page
for await (const p of page.pages()) {
  console.log(`${p.data.length} posts`);
}

Drive pagination off hasMore and the cursor — never off the item count. The upstream API may return a short or even empty page while hasMore is still true. Stopping when a page looks empty will cut your results short.

// Correct
let page = await client.instagramLive.searchPosts("travel");
while (page.hasNextPage()) {
  page = await page.nextPage();
  process(page.data);
}

// Wrong — stops early on a legitimately empty page
while (page.data.length > 0) {
  page = await page.nextPage();
}

Methods

All methods accept fields to select which fields come back, and all paged methods accept cursor to resume from a previous response.

Method	Returns
`searchPosts(query, options?)`	`CursorResult<InstagramPost>`
`getPostsByUser(identifier, options?)`	`CursorResult<InstagramPost>`
`getPost(postId, options?)`	`InstagramPost \| null`
`getComments(postId, options?)`	`CursorResult<InstagramComment>`
`getPostInteractingUsers(postId, interactionType, options?)`	`CursorResult<InstagramUser>`
`searchUsers(name, options?)`	`CursorResult<InstagramUser>`
`getUser(identifier, options?)`	`InstagramUser \| null`
`getUserConnections(identifier, connectionType, options?)`	`CursorResult<InstagramUser>`

interactionType is "commenters" or "likers". connectionType is "followers" or "following". Both are typed unions, so invalid values fail at compile time. getPost and getUser are single-item lookups and return the object directly, or null if nothing was found.

Examples

import { XpozClient } from "@xpoz/xpoz";

const client = new XpozClient({ apiKey: "your-api-key" });

// Search posts by keyword
const posts = await client.instagramLive.searchPosts("travel", {
  fields: ["id", "caption", "likeCount"],
});

// A user's recent posts
const userPosts = await client.instagramLive.getPostsByUser("natgeo", { fields: ["id", "likeCount"] });

// Who liked a post
const likers = await client.instagramLive.getPostInteractingUsers(
  "3820275679950397949_495767729",
  "likers",
  { fields: ["id", "username"] }
);

// Who a user follows
const following = await client.instagramLive.getUserConnections("natgeo", "following", {
  fields: ["username"],
});

// Single lookups
const post = await client.instagramLive.getPost("3820275679950397949_495767729");
const user = await client.instagramLive.getUser("natgeo");

Resuming From a Cursor

Cursors are opaque strings you can persist and reuse later, which is useful for long-running or resumable jobs:

const page = await client.instagramLive.searchPosts("travel");
const savedCursor = page.nextPageCursor;

// Later, in another process
const resumed = await client.instagramLive.searchPosts("travel", { cursor: savedCursor ?? undefined });

A cursor is only valid for the same query on the same endpoint. Reusing one elsewhere is rejected with a 400.

Field Selection

Live methods accept the same fields values as their database-backed counterparts — see the TypeScript SDK Reference for the full Instagram field lists. Live methods do not support since / until date filtering. The upstream API accepts only the query and a cursor, so use client.instagram.searchPosts() when you need a date range.

Connection Details

Live methods talk to the Xpoz REST API (https://api.xpoz.ai) rather than the MCP server, using the same API key. Override the base URL when needed:

const client = new XpozClient({ apiKey: "your-api-key", apiUrl: "https://api.xpoz.ai" });

The XPOZ_API_URL environment variable does the same thing.

​What Live Data Is

​No connect() Required

​CursorResult

​Navigating Pages

​Methods

​Examples

​Resuming From a Cursor

​Field Selection

​Connection Details

What Live Data Is

No connect() Required

CursorResult

Navigating Pages

Methods

Examples

Resuming From a Cursor

Field Selection

Connection Details