Virtual assistant exchanges feed reference

James Lett

Updated 03 September 2026 10:21

The virtual assistant exchanges feed provides read-only access to the questions learners ask Aptem's virtual assistant (AVA). Each row is one question, so a session in which a learner asks five questions produces five rows.

The feed returns the learner's question and the topic it was answered from. It does not include the assistant's reply. Use it to report on virtual assistant usage, see which topics learners are asking about, and track activity by programme or learner.

This page covers the fields the feed returns, the query options you can use, and how it links to other feeds. For general information about OData v2, see Introduction to OData v2. For a full explanation of how query options work, see How to query OData v2 feeds.

Fields

Field	Type	Description
`Id`	String	The unique identifier of the learner's message, for example `msg_0a4f1c72-9d3b-4e88-9a10-5f7c2b6d4e33`
`ConversationId`	String	The conversation the exchange belongs to, for example `conv_5e1b8d40-72af-4c19-8b6e-3d9a0f1c4b27`. Rows from the same session share this value
`LearnerId`	Integer	The learner who asked the question. Matches the `Id` field in the Users v1 feed
`ProgrammeId`	Integer, nullable	The programme the learner was working on. Null for exchanges recorded before the programme was captured
`Question`	String	The learner's message, as they wrote it
`Topic`	String, nullable	What the exchange was about, derived from the assistant capability that answered it. Null for exchanges recorded before the topic was captured
`Date`	DateTimeOffset	The date and time the learner sent the message, in UTC

Topic values

Value	What it covers
`general`	General conversation, where no specific capability handled the question
`learningplan`	Questions about the learner's learning plan
`recent_activity`	Questions about the learner's recent activity
`evidence`	Questions about evidence
`actions`	Questions about the learner's actions
`reviews`	Questions about reviews
`whats_new`	Questions about what has changed in the platform
`using_aptem`	Questions about how to use Aptem

Understanding the data structure

Each row is a single question a learner sent to the virtual assistant. A session typically contains several questions, all sharing the same ConversationId.

For example, if a learner asks three questions in one session, the feed returns three rows with the same ConversationId but different Id, Question, Topic and Date values.

Querying the feed

The virtual assistant exchanges feed supports the same query options as other v2 feeds:

Option	What it does	Example
`$select`	Return only the fields you specify	`$select=LearnerId,Topic,Date`
`$filter`	Filter results by field values	`$filter=ProgrammeId eq 312`
`$orderby`	Sort results by a field (add `desc` for descending)	`$orderby=Date desc`
`$top`	Return only the first N items	`$top=50`
`$count`	Include the total count of matching items	`$count=true`
`Prefer` header	Request a smaller page than the 1,000-item default	`Prefer: odata.maxpagesize=100`

Question cannot be used in $filter or $orderby. An invalid query, such as filtering on Question or naming a field that does not exist, returns 400 Bad Request with a standard OData error body. Match on the code value, never on the message, as the message wording can change between releases.

For a detailed explanation of each option and how to use them in the browser and Excel, see How to query OData v2 feeds.

Filter operators

Operator	Meaning	Example
`eq`, `ne`	Equals, not equals	`ProgrammeId eq 312`
`gt`, `ge`, `lt`, `le`	Greater/less than (or equal)	`Date ge 2026-07-01T00:00:00Z`
`and`, `or`, `not`	Combine clauses	`Topic eq 'safeguarding' and Date ge 2026-07-01T00:00:00Z`

Example queries

You can use these example queries in your URL, you will need to change the ‘filters’ such as LearnerId and ProgrammeId to match the Id’s within your tenant.

All exchanges for a specific learner, most recent first:

/odata/2.0/VirtualAssistantExchanges?$filter=LearnerId eq 48213&$orderby=Date desc

All exchanges on a specific programme this month:

/odata/2.0/VirtualAssistantExchanges?$filter=ProgrammeId eq 312 and Date ge 2026-08-01T00:00:00Z&$orderby=Date desc

Exchanges on a specific topic:

/odata/2.0/VirtualAssistantExchanges?$filter=Topic eq 'learningplan'&$orderby=Date desc

All exchanges in a single conversation, in order:

/odata/2.0/VirtualAssistantExchanges?$filter=ConversationId eq 'conv_5e1b8d40-72af-4c19-8b6e-3d9a0f1c4b27'&$orderby=Date

Usage by topic over a period, without returning the question text:

/odata/2.0/VirtualAssistantExchanges?$select=LearnerId,Topic,Date&$filter=Date ge 2026-07-25T00:00:00Z

Count of exchanges in the last 30 days:

/odata/2.0/VirtualAssistantExchanges?$filter=Date ge 2026-07-25T00:00:00Z&$count=true&$top=0

Results are always paged. Each page returns up to 1,000 items. When more items are available, the response includes an @odata.nextLink field containing the URL of the next page. The next link carries an opaque $skiptoken and preserves your $filter, $orderby and $count, so follow it until it is no longer present in the response.

To request a smaller page, send the Prefer: odata.maxpagesize=N header. A value above 1,000 is reduced to 1,000.

Do not page by incrementing $skip. It is available for one-off offset jumps up to 10,000 rows, beyond which the request is rejected, and offset paging can miss or duplicate rows when data changes between requests.

Requests to the v2 feeds are also rate limited. See Introduction to OData v2 for the current limits and how to handle a 429 response.

Linking to v1 feeds

The virtual assistant exchanges feed can be combined with the Users v1 feed to enrich reports with learner details. Join on LearnerId to bring in the learner's name, programme information, case owner, and other profile data.

Virtual assistant exchanges field	v1 feed	v1 field	What it gives you
`LearnerId`	Users	`Id`	Learner name, current programme, programme start and end dates, case owner, and other learner details

ProgrammeId can be null, so filter out null values before joining if you need a complete match. There is no tutor field on this feed. Use the LearnerId join to the Users v1 feed to bring in tutor details.

Using the feed in Excel

Query the feed URL directly with your field selection in the URL.

Example Power Query M code:

let Source = OData.Feed( "https://yourtenant.aptem.co.uk/odata/2.0/VirtualAssistantExchanges?$select=Id,ConversationId,LearnerId,ProgrammeId,Question,Topic,Date", [#"X-API-Token"="YOUR_API_KEY"], [Implementation="2.0"] ) in Source

Getting help

If you have questions about the virtual assistant exchanges feed or need your API key:

Contact your Implementation Consultant if you are still in implementation
Contact your Customer Success Manager if you are a live customer
Raise a support ticket