OData feed

Load Wordsmith reports, usage and tasks into Power BI, Excel, Tableau or any OData v4 client.

The OData feed is enabled per organisation. To turn it on, contact your Wordsmith account manager. Then an administrator chooses what it publishes under Settings → BI feed.

Wordsmith publishes a read-only OData v4 feed that BI tools load as tables. Tool-by-tool steps are in Power BI and Excel and Tableau. The feed gives you three kinds of table:

• Reports: one row per document, with one column per report column, typed as numbers, dates, yes/no or text.
• Usage and value: sessions, interactions, active users, hours saved and cost saved, per day or per user, team, agent or skill.
• Tasks: one row per task, and tasks created and completed per day with their average turnaround.

The feed is read-only. It returns what the API key’s user can see in Wordsmith. A table appears only when the key can read it and its feature is on for your organisation. A key limited to some scopes sees only the tables for those scopes. Of the features, Tasks needs Tasks, and TaskDaily and TaskDailyCoverage also need the Tasks view of Usage and value.

​

Choose what is published

Nothing is published until an administrator turns it on. Under Settings → BI feed, an administrator:

1. Turns on the BI feed. While it is off, every feed request is refused.

2. Chooses the usage tables: Publish usage figures, Include one row per person for UsageByUser and UsageDailyByUser, and Include one row per session for UsageSessions, which needs one row per person.

3. Chooses the task tables: Publish daily task counts (TaskDaily, TaskDailyCoverage) and Publish the task list (Tasks). The task tables can be limited to tasks assigned to some teams.

4. Chooses what Tasks shows about each task. With Include names and email addresses off, the name and email columns are empty, and CreatorKey and AssigneeKey hold a coded ID that stays the same between refreshes. With Include titles, matters and tags off, those columns are empty, MatterMasked included. A task in a matter the key’s user cannot open has an empty Matter and MatterMasked set to true.

   The coded ID is a pseudonym, not anonymity. It keeps names off the dashboard, but Id and Url still identify each task, so whoever holds the API key can open a task in Wordsmith and see who it belongs to. Treat the key and the BI file as personal data.

5. Turns on Publish reports for the Reports table and each report’s own feed. Reports are then published one at a time: open a report and turn on Available to BI tools in its menu, or set available_to_bi_tools with Update report. Reports lists only published reports.

6. Chooses who may publish a report. People who manage the BI feed always may. With Let report editors publish their reports on, so may anyone who can edit the report. Anyone who can edit a report can always stop publishing it. A report published while the feed or Publish reports is off says so: BI tools can’t load it until both are on.

Published reports lists every published report, newest first, with Stop publishing beside each. A report you can’t open is listed without its name, and you can still stop publishing it.

A setting that needs a feature your organisation doesn’t have says so and can’t be turned on. For example, Include one row per person needs per-person usage in your plan.

Reading the feed also needs a role that allows the BI feed. The Admin role does; for other roles, an administrator adds the permission under Settings → Roles.

​

See who reads the feed

Under Settings → BI feed, Connected keys lists each API key and connected app that has loaded data from the feed: its owner, the tool (Power BI or Excel, Tableau, or another tool), the tables and reports it read, and when. Reads are noted at most once every 15 minutes per table or report, and the audit log records a BI feed read event at most once a day per key. If writing that event fails, it is tried again at most every 15 minutes, so a short refresh can leave a day without one. A report someone else’s key read shows its name only if you can open that report, and each key lists its 20 most recent reports with a count of older ones.

To stop a key reading the feed, revoke it under Settings → API Keys. To stop every key, turn the feed off.

A table the feed doesn’t serve to a key is refused with the reason: 403 when it isn’t published, or when the key lacks the permission it needs (the message names it, for example usage:read), and 404 when your organisation doesn’t have the feature.

​

Connect

Every tool connects with an API key and Basic authentication:

1. In Wordsmith, create an API key for the user whose view the tool should load. A key limited to some scopes needs reports:read, usage:read and tasks:read for the tables it loads.

2. Point the tool’s OData connector at the feed URL for your region:

   https://api.wordsmith.ai/api/v1/odata
   

   In the US region, use https://api.us.wordsmith.ai/api/v1/odata. Power BI and Excel take this URL and list every table. Tableau takes it too and lists the tables to drag onto its canvas (see Tableau).

3. Sign in with Basic authentication (often labelled Username and Password). Enter any user name, and the API key as the password.

The feed’s sign-in prompt does not reach the tool, so choose Basic yourself rather than waiting for the tool to ask. A scheduled refresh uses the same credential, stored with the published data source.

​

Tables

Table	One row per	Key columns
Reports	Published report you can read	Name, RowCount, Status, FeedUrl
UsageDaily	Day	Sessions, Interactions, ActiveUsers, HoursSaved, CostSavedExternal
UsageByUser, UsageByTeam, UsageByAgent, UsageBySkill	User, team, agent or skill	The same figures for the period, plus CostSavedInHouse
UsageDailyByUser, UsageDailyByTeam, UsageDailyByAgent, UsageDailyBySkill, UsageDailyBySurface, UsageDailyByWorkType	Day and user, team, agent, skill, surface or work type	Date, Key, Name, Sessions, Interactions, AgentSteps (skills: Invocations)
UsageSessions	Session and day	Date, SessionKey, UserKey, AgentKey, WorkType, Surface, Started, Interactions, AgentSteps, EstimatedMinutes, CalibratedMinutes, MainEffortCategory
Tasks	Task	Status, Priority, AssigneeKey, AssigneeName, SourceChannel, Tags, CompleteBy, CreatedAt
TaskDaily	Day	Created, Completed, AverageTurnaroundHours
TaskDailyCoverage	Period (one row)	PeriodStart, PeriodEnd, UntrackedTasks, LateHistoryTasks

TaskDaily counts completions from each task’s recorded status history. A task created before Wordsmith recorded that history has none, so its completion is missing from Completed and AverageTurnaroundHours. TaskDailyCoverage gives the period’s UntrackedTasks (tasks with no recorded history) and LateHistoryTasks (tasks whose history starts after the day they were created). When either is above zero, completions are undercounted. Load it with the same period options as TaskDaily.

The UsageDailyBy… tables are long tables for slicing activity by any date range: one row per day and person, team, agent, skill, surface (web app, Word, Slack…) or work type. For people, teams, agents and skills, a row’s Key is the same entity’s Key in the matching UsageBy… table, so you can relate the two in your model; surfaces and work types have no period table. People in no team appear in UsageDailyByUser but not in UsageDailyByTeam. Days with no activity have no row, and a count that older data didn’t record is empty rather than zero. People, teams and agents carry their current name. A skill carries the latest name recorded in each week of days, so a skill renamed during the period, or with no recorded name that week, can show a different or empty Name on some days; take one skill name from UsageBySkill through Key. These tables carry activity counts only. For hours and cost saved, use UsageDaily (per day) or the UsageBy… tables (per person, team, agent or skill for the period). A person’s day counts towards every team they belong to, so team rows can add up to more than the organisation total. UsageDailyByUser appears only when per-person usage is published.

UsageSessions shows the sessions behind the usage figures: one row per session for each day it was active. Started is true on the day the session began, the one day it counts as a session. UserKey is the session’s owner, using the same keys as UsageByUser.Key, and AgentKey matches UsageByAgent.Key. In a session several people posted in, every row counts under its owner, whereas UsageDailyByUser credits each person’s own turns. EstimatedMinutes is Wordsmith’s estimate of the manual minutes the session saved, on its first day only. It is empty when the session has no estimate. CalibratedMinutes applies your organisation’s calibration, as the dashboard does, and MainEffortCategory names the kind of work most of those minutes were for. DocumentTypes, Languages and Jurisdictions list what the session dealt with, separated by ; . The table has no titles, prompts or summaries. These minutes don’t add up to UsageDaily’s hours: the daily figures also count report cells, and estimate sessions without their own estimate from their counts. Rows exist only for days Wordsmith has computed per-session rows for, so older days may have none.

Hours and cost saved are estimates priced with your organisation’s rates. Organisation figures include your organisation’s calibration, as on the Usage and value dashboard.

​

Period and scope

The usage tables and TaskDaily cover the last 30 days unless the URL says otherwise. Add options to the feed URL to change it:

Option	Values
period	this_month, last_month, last_7_days, last_30_days, last_quarter, lifetime, custom
start, end	ISO dates, for example 2026-01-01. Required with period=custom
scope	company (the default) or me. Only UsageDaily, TaskDaily and TaskDailyCoverage take it

The options on the feed URL carry into each table that takes them. For example, to load the whole of 2026: https://api.wordsmith.ai/api/v1/odata?period=custom&start=2026-01-01&end=2026-12-31.

Organisation figures need permission to view company analytics. Per-user rows need your organisation to show named users on the dashboard.

​

A report as a table

Each report has its own feed. Copy it from the FeedUrl column of the Reports table, or build it from the report ID:

https://api.wordsmith.ai/api/v1/odata/reports/{report_id}

Connect to it the same way. It has three tables:

Table	One row per	Columns
Rows	Document	RowId, DocumentName, FileId, PendingCells, FailedCells, UntypedCells, then one column per report column
Cells	Answer	RowId, ColumnId, ColumnName, Value, Status, Reviewed, UpdatedAt
Columns	Report column	Id, Name, PropertyName, UnitPropertyName, Type, Prompt, Options

In Rows, a column’s name is the report column’s name, with spaces and punctuation replaced by _. A name that is also a filter keyword, such as null or not, gets _2 added. A number column is followed by a _unit column, such as Rent_unit, holding the answer’s unit or currency. Check it before you add amounts together. The Columns table maps each report column to its names in Rows.

A cell in Rows is empty when Wordsmith has not answered it yet, could not answer it, or gave an answer that is not the column’s type. Each row counts these:

• PendingCells: cells still being computed.
• FailedCells: cells that failed.
• UntypedCells: answers that do not fit the column’s type, such as “not stated” in a date column.

The Cells table keeps every answer as text, with its status.

​

Filters and limits

The feed applies filters that a tool sends as $filter, as Power BI does. A comparison with an empty value follows OData: a row is kept only when the whole filter is true, so not contains(Title,'x') leaves out rows with no Title. A filter that compares values of different types, such as a number column with text, is refused with 400. It supports comparisons (eq, ne, gt, ge, lt, le), and, or, not, and the functions contains, startswith, endswith, tolower, toupper, trim, length, year, month, day and date.

The feed refuses with 501 what it cannot apply, rather than returning rows a tool would trust as filtered:

• Sorting ($orderby) and counting ($count). Sort and count in your tool after the table loads.
• Other $filter functions and arithmetic operators. Apply that filter in your tool after the table loads.

Tasks pages in the same order as the app’s task list. A task whose priority or position changes while a tool reads the table can be read twice or missed until the next refresh.

Each request counts towards your organisation’s rate limit. A tool reads a table in pages, so a large report takes one request per page. Every refresh reads each table again from the start.

​

If the feed key is in the URL

If your tool cannot use Basic authentication, add the key to the URL as ?api_key= and connect anonymously. The key then appears in the URL and in your workbook or report file, so prefer Basic.