> ## Documentation Index > Fetch the complete documentation index at: https://wordsmithai.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # OData feed > Load Wordsmith reports, usage and tasks into Power BI, Excel, Tableau or any OData v4 client. > [!NOTE] > > 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](https://wordsmithai.mintlify.site/power-bi.md) and [Tableau](https://wordsmithai.mintlify.site/tableau.md). 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. > [!WARNING] > > 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](https://wordsmithai.mintlify.site/api-reference/reports/update-report.md). `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](https://wordsmithai.mintlify.site/authentication.md) 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](https://wordsmithai.mintlify.site/tableau.md)). 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](https://wordsmithai.mintlify.site/rate-limits.md). 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.