A report often needs a dataset that is itself computed from other datasets: a build plan from sales and inventory, a metrics table from a raw export. Copying those files into one upload hides which versions went into it, so the next refresh is a guess.
Derived data sources name the data sources they are built from. This is an early capability. You can declare those inputs, report the versions a build actually used, and read the status on the data source page. Threaded does not build the derived file for you yet. See Derived Data Source Transforms.
#Key Concepts
Input — Another data source in the same organization that a derived source is built from. The link is an edge from the derived source to that input.
Snapshot — The input’s versions are complete replacements, such as a cumulative export. The build reports the one version it read.
Append — Each version of the input holds only new rows, such as this week’s file. The edge is still recorded as a single version: the newest one the build read. Threaded does not yet rebuild a window of older versions for you.
Lineage — The record, on the derived source’s version, of which input version each edge supplied, plus the coverage dates that build covers.
Stale — The derived source has a current version, lineage was reported for it, and at least one input’s current version is not the version that build used. That includes a newer upload and a rollback. It does not mean “newer” by itself.
#Who can use it
Anyone who can view the organization, except operators, can read inputs and the Inputs panel. Adding an input, changing its mode, and removing it require an edit role — Owner or Editor — and Manufacturing Reports must be enabled for the organization.
Managed Threaded caches, such as threaded and threaded_form, cannot have inputs. Threaded builds those itself.
#Declaring inputs
There is no control in the app for adding an input yet. Use the API. The derived source is the slug in the path; the input is another source’s slug in the body.
POST /api/v2/reporting/organizations/<organization_uuid>/data-sources/<slug>/inputs/
{"input_slug": "raw", "mode": "snapshot"}
mode is snapshot or append. A successful create returns 201. List the inputs with GET on the same path. They come back ordered by the input’s slug.
Change the mode, or remove the input:
PATCH /api/v2/reporting/organizations/<organization_uuid>/data-sources/<slug>/inputs/<input_slug>/
{"mode": "append"}
DELETE /api/v2/reporting/organizations/<organization_uuid>/data-sources/<slug>/inputs/<input_slug>/
Changing the mode or removing the edge does not rewrite lineage already stored on versions you have published. A removed input simply stops appearing on the panel.
Threaded refuses an edge that would break the graph. The message is on input_slug:
- Same source. “A data source cannot be its own input.”
- Cycle. “This input would create a cycle: it already depends on this data source.” If
metricsalready readsraw,rawcannot takemetricsas an input. - Depth. “This input would make a chain N levels deep. The maximum is 3 levels.” Depth counts edges through the new edge, upstream and downstream together.
raw→a→b→cis three edges and is allowed. A fourth edge on that chain is refused. - Duplicate. “This data source already reads from that input.”
- Other organization, or an unknown slug. Inputs stay inside the organization. An unknown slug returns “Unknown data source.” A source from another organization returns “Input must belong to the same organization.”
- Managed source. “Managed data sources are built by Threaded and cannot have inputs.”
A view-only member can GET the list. POST, PATCH, and DELETE return 403.
#Reporting lineage when a version completes
Uploading a derived file is the same two-step upload as any other data source: request the upload, put the file, then complete it. See Manufacturing Report Data Sources. On complete, send the versions the build read and the dates that file covers:
POST /api/v2/reporting/organizations/<organization_uuid>/data-sources/<slug>/versions/<version_uuid>/complete/
{
"input_versions": ["<input version uuid>"],
"data_from": "2026-01-01",
"data_through": "2026-10-12"
}
input_versions is one version uuid per declared input. For an append input, send the newest version the build read. Each version must belong to a declared input, must have finished uploading, and must be in this organization. Send every input: a missing one returns “Missing a version for input: …”. Two versions for the same input returns “Report one version per input.”
data_from and data_through are optional calendar dates. Either one can be omitted. If both are sent, data_through cannot be earlier than data_from.
If the body is wrong, the complete call returns 400 and the upload stays incomplete. Omit input_versions when the build did not record what it read. Threaded will not invent lineage, and the panel will say so.
#Reading the Inputs panel
Open the data source from Reporting → Data sources. The sidebar and the full page show the same Inputs section, and only when the source has at least one input. A source with no inputs shows nothing here.
The section leads with when the current version was published:
- Last built followed by the date and time, from that version’s upload time. For example, “Last built August 12, 2026 3:29 PM”.
- Not built yet when the source has no current version.
Under that, the coverage the build reported. A missing bound is left out. Both bounds read “Data from Jan 1, 2026 through Oct 12, 2026”. Only a start reads “Data from Jan 1, 2026”. Only an end reads “Data through Oct 12, 2026”. If the build reported neither date, the line is absent.
Each input is one row: its title, a Snapshot or Append chip, a status chip, and a short line about the revisions.
| Status | When you see it | The line under the chip |
|---|---|---|
| Up to date | Lineage was reported and the input’s current version is the one this source was built from. | “Built from revision 2” |
| Newer version available | The input’s current revision is higher than the one this source was built from. | “Built from revision 2, current is revision 5” |
| Input rolled back | The input’s current revision is lower than the one this source was built from. | “Built from revision 5, current is revision 3” |
| Input changed | Lineage names a version, but that version no longer has a revision number to compare, so Threaded will not call it newer or a rollback. | “Built from none, current is revision 5” |
| No data yet | The input has no published version. This wins over the other chips. | “This input has no published version yet” |
| Lineage not reported | The input has a published version, and no build has reported which version it used. | “No build has reported which version of this input it used” |
Alerts sit above the rows:
- Stale: “Stale: an input’s current version is not the one this source was built from (a newer version, or an input rolled back).” This is the derived source’s own inputs. It appears when any row is Newer version available, Input rolled back, or Input changed.
- Behind upstream: “Behind upstream: something up to 3 levels upstream needs attention.” Under it, each source that needs attention, with how far away it is and why. A direct input reads “directly upstream”. Further sources read “2 levels upstream” or “3 levels upstream”. The reason is “out of date” when that source’s own inputs differ from what built it, or “last build failed” when its newest build failed and no later publish came after that build finished. A version published while the build was still running does not clear the failure. A source can be both stale and behind upstream: stale is this source, behind upstream is the chain it reads from.
- Freshness unknown: “Freshness unknown: no build has reported which input versions this version was built from.” This appears when the source has a current version and lineage was not reported for every input. It does not appear on Not built yet.
- Built from the current version of every input. The green line. It appears only when the source has a current version, lineage was reported, nothing is stale, nothing upstream needs attention, and every input has a published version. A source that was never built, or that has an input with no data, does not show it.
#Why This Matters
The version history of a derived file tells you which file is current. The inputs and the lineage tell you which inputs that file was built from, and whether those inputs have moved since. You can see a newer upload, a rollback, a failed build further up the chain, or a build that never said what it read, without opening the file.