Filtering, Sorting and Paging API Results
Use the filter, filterValues, sortBy and paging query parameters on Airia's list endpoints, and see which filters each conversation endpoint supports.
Airia's list endpoints share a common set of query parameters for searching, filtering, sorting and paging. This page explains how they work and lists the filters each conversation endpoint supports.
Unsupported filters are ignored, not rejected. Each endpoint honours only the filterValues keys listed for it below. If you send a key the endpoint doesn't support, or a value it can't parse, the request still succeeds and that filter is skipped, so you may get back more results than you expect. Check the table for the endpoint you are calling.
Common parameters
| Parameter | Example | What it does |
|---|---|---|
filter | filter=quarterly report | Free-text search. Matches results whose searchable fields contain the text, ignoring case. Each endpoint decides which fields are searchable. |
filterValues[<key>] | filterValues[ProjectId]=<guid> | A filter on one field. The key goes in square brackets. Send several to combine them; results must match all of them. |
sortBy | sortBy=CreatedAt | The field to sort by. |
sortDirection | sortDirection=ASC | ASC for ascending; DESC (the default) for descending. |
pageNumber | pageNumber=2 | The page to return, starting at 1. Defaults to 1. |
pageSize | pageSize=50 | The number of results per page. |
Parameter names and filterValues keys aren't case-sensitive: filterValues[projectid] and FilterValues[ProjectId] are the same filter.
Always set pageSize. If you leave it out, the endpoint returns every matching result in one response.
Where a filter accepts several IDs, separate them with commas: filterValues[ProjectId]=<guid1>,<guid2>. A result matches if it matches any of them. IDs that aren't valid GUIDs are dropped; if none are valid, that filter is skipped.
Requests authenticate with an API key in the X-API-Key header. See API Keys. The examples below use https://api.airia.ai; on another region or a self-managed instance, use your own Airia API URL.
Conversation feed
GET /v1/Conversations/feed lists conversations across your account, for auditing. It requires an administrator role (platform admin, admin, read-only admin or project admin) and isn't available to end users. An API key needs Include Conversations turned on. Results are limited to the projects you can access.
| Parameter | Format | Notes |
|---|---|---|
filter | Text | Searches the conversation title and name. |
filterValues[ProjectId] | GUIDs, comma-separated | Conversations in these projects. |
filterValues[AgentId] | GUIDs, comma-separated | Conversations with these agents. |
filterValues[UserId] | GUIDs, comma-separated | Conversations started by these users. |
filterValues[UserGroupId] | GUIDs, comma-separated | Conversations from members of any of these groups. |
filterValues[StartDate] and filterValues[EndDate] | Dates, ISO 8601 | Conversations created within this range. Send both: if either is missing or can't be read as a date, the date filter is skipped. Include a time zone offset (for example 2026-01-31T23:59:59Z); without one, the server's time zone is used. |
filterValues[metadata.<key>] | Text | See Filtering on conversation metadata. |
The feed never returns conversations created before 12 May 2025, even if StartDate is earlier.
Results are sorted by CreatedAt, newest first, unless you set sortBy. The response contains items and totalCount, the total number of matching conversations.
GET https://api.airia.ai/v1/Conversations/feed?filterValues[ProjectId]=<guid1>,<guid2>&filterValues[StartDate]=2026-01-01T00:00:00Z&filterValues[EndDate]=2026-01-31T23:59:59Z&pageNumber=1&pageSize=25A user's conversations
GET /v2/Users/{userId}/conversations lists one user's conversations: the ones they started and the ones shared with them. Signed in as a user, you can list only your own. To list any user's conversations, use a service account API key with Include Conversations turned on. GET /v2/Users/{userId}/conversations/summaries takes the same parameters and returns a lighter response without token counts, cost or the full latest message.
| Parameter | Format | Notes |
|---|---|---|
filter | Text | Searches the conversation title. |
filterValues[DeploymentId] | GUIDs, comma-separated | Conversations from these deployments. |
filterValues[IsBookmarked] | true or false | Bookmarked, or not bookmarked, conversations. |
filterValues[LastExecutionStatus] | Comma-separated: InProgress, Completed, Failed, NotApplicable | Conversations whose most recent agent run has one of these statuses. |
filterValues[metadata.<key>] | Text | See Filtering on conversation metadata. |
These endpoints don't support the feed's project, agent, user, group or date filters. If you send them, they are ignored.
| Paging parameter | Notes |
|---|---|
includeTotalCount | true by default. Set it to false when you don't need the total; the response's totalCount is then null and the request is faster. |
Results are sorted by UpdatedAt, most recently active first, unless you set sortBy. You can sort by Title, CreatedAt, UpdatedAt, IsBookmarked, LastExecutionStatus, InputTokens, OutputTokens, TotalTokens or Cost. The response contains items, totalCount and hasMore, which is true when there is another page.
GET https://api.airia.ai/v2/Users/{userId}/conversations?filter=hello&filterValues[IsBookmarked]=true&pageNumber=1&pageSize=10&sortBy=UpdatedAt&sortDirection=DESCIf sortBy names a field the endpoint can't sort by, the request still succeeds but the results aren't sorted.
Filtering on conversation metadata
Conversations can carry metadata: key-value labels your application attaches when it creates the conversation. Both conversation endpoints above filter on it with filterValues[metadata.<key>]=<value>:
GET https://api.airia.ai/v2/Users/{userId}/conversations?filterValues[metadata.customer_id]=ACME-1042&filterValues[metadata.channel]=web- Exact match. The value must match exactly, including case. Conversations without that metadata key aren't returned.
- Several keys are combined. A conversation must match every metadata filter you send.
- Keys are 1–64 characters of lowercase letters, digits,
_,.and-. Keys are matched without regard to case. - Values can be up to 512 characters and can't contain control characters.
- Encoding. URL-encode the value.
%26is a literal&, and+is a space, so send a literal plus sign as%2B.
Unlike other filters, an invalid metadata filter is rejected: the request returns 400 Bad Request instead of silently returning unfiltered results.