Sign inGet started
Docs
Get started

Create Analytics Data Source

Create a data source, owned by the key's creator, for Analytics panels to read. A sync source fetches from an app's read action on a schedule and stores the rows: name the app, the action and a connection, with its arguments. A live source fetches from an action only when a drill-down opens, with that view's values. A merge combines your sync or fixed sources with SQL and code. A fixed source holds rows you send, up to 1,000, and is never refetched. A sync or merge source starts its first fetch now: follow it with Get Analytics Data Source Result. Incremental refreshes (fetching only changed records) stay off unless you set them with Update Analytics Data Source. An identical source you already have is reused rather than duplicated.

POST

Headers

Optional headers
string

Optional. The id of the organization to act in. Leave it out to act in the API key's own organization. Here a key acts in another organization only as one of its members: with "Use this key across all of your organizations" on, in an organization its creator belongs to with a role. Child organizations and MindCloud staff access do not reach this endpoint. Every response's X-Company-Id header names the organization it acted in. See Organizations.

Body

Arguments
stringrequired

What kind of source: sync, live, merge or fixed.

  • syncFetched from an app action on a schedule and stored.
  • liveFetched from an app action when a drill-down opens, with its values; never stored.
  • mergeCombines other sources with SQL and code.
  • fixedRows you supply; never refetched.
string

A name. Left out, one is written from what it fetches.

A name for the source. Left out, one is written from what it fetches.

string

What the data holds, in a sentence. Left out, one is written from the data.

string

For sync and live: the app, by id or slug, from List Universal Apps.

The app to fetch from, by id or slug, from List Universal Apps.

string

For sync and live: the app's read action, by id or slug, from List Universal Actions.

The app's read action, by id or slug, from List Universal Actions.

string

For sync and live: the connection to fetch with, from List Connections.

The connection to fetch with, from List Connections.

object

For sync and live: the action's arguments, as Get Universal Action lists them.

The action's arguments, { argumentKey: value }, as Get Universal Action lists them. Values may use date expressions such as {{now-2y}}.

object

For sync and live: the action's options.

The action's options, such as { "pagination": { "mode": "all" } }.

object

For sync and live: a filter and sort the app applies before the rows are stored.

A filter and sort the app applies before the rows are stored. The action must support them exactly, or the request is refused.

  • filterany

    The filter the app applies, as Get Universal Action describes it. Values must be literals.

  • sortany

    The sort the app applies.

number

For sync and merge: how often it refreshes in full, in seconds.

How often a sync or merge source refreshes in full, in seconds, up to 604800. A source that takes long to fetch may be held to a longer interval; the answer says what was set.

array of object

For merge: the sources to combine, each with an alias and optional SQL.

For a merge source: the sources it combines.

  • dataSourceIdstringrequired

    The input source, a sync or fixed source of yours, from List Analytics Data Sources.

  • aliasstringrequired

    The name the merge SQL and code read this input by.

  • querystring

    SQL that shapes this input before the merge, reading it as `src`. Leave it out to use the input as is.

string

For merge: JavaScript that receives each input by its alias and returns the combined rows.

For a merge source: JavaScript that receives each input by its alias and returns the combined rows. Required when there is more than one input.

array of object

For fixed: the rows, as objects with the same keys.

For a fixed source: the rows, as objects with the same keys, up to 1000. They replace the source's data.

object

Which columns hold dates, for page date filters. Left out, they are worked out from the data.

Which columns hold dates, for page date filters. Left out (or null on update), they are worked out from the data after each refresh.

  • primaryDateKeystring

    The column page date filters use.

  • primaryDateKeyGrainstring

    That column's grain, such as day or month.

  • createdDateKeystring

    The column holding when each record was created.

  • updatedDateKeystring

    The column holding when each record last changed.

  • hasNoDatesboolean

    True when the source has no date column.

Response fields

idstring

The data source's id.

namestring

The data source's name.

descriptionstring

What the data holds, in a sentence.

createdBystring

The userId of the member who created it, from List Members: the key's creator for their own sources.

typestring

sync: fetched from an app action on a schedule and stored; live: fetched from an app action when a drill-down opens, with its values, and never stored; merge: combines other sources with SQL and code; fixed: rows you supply, never refetched.

  • sync
  • live
  • merge
  • fixed
appIdstring

The app a sync or live source fetches from, from List Universal Apps. Null for merge and fixed sources.

actionIdstring

The app action it fetches with, from List Universal Actions. Null for merge and fixed sources.

actionNamestring

The app action's name.

connectionIdstring

The connection it fetches with, from List Connections. Null for merge and fixed sources.

statusstring

Where its data stands. live: a live source, which has no stored data; neverFetched: no fetch has run yet; noData: a fixed source with no rows yet; draft: waiting for its first fetch; queued: a fetch is waiting to start; refreshing: a fetch is running; ready: its rows are stored; empty: the last fetch returned no rows; failed: the last fetch failed (see message).

  • live
  • neverFetched
  • noData
  • draft
  • queued
  • refreshing
  • ready
  • empty
  • failed
rowCountnumber

How many rows the last fetch stored.

fetchedOndate

When the stored rows were fetched.

messagestring

Why the last fetch failed, when it did.

refreshIntervalSecondsnumber

How often a sync or merge source refreshes in full, in seconds. Null for live and fixed sources.

isIncrementalEnabledboolean

For a sync source, whether incremental refreshes (fetching only changed records between full refreshes) are switched on. Null for other types.

incrementalIntervalSecondsnumber

How often incremental refreshes run, in seconds, while they run. Null otherwise.

isPausedboolean

True when every page that uses it is paused or deleted, so its scheduled refresh is skipped.

panelCountnumber

How many panels on its owner's pages read it.

isUnusedboolean

True when no panel reads it and it has not changed for a day: the sources the app's cleanup offers to delete.

createdOndate

When it was created.

updatedOndate

When it last changed.

appVersionstring

The app version a sync or live source is pinned to.

latestAppVersionstring

The app's current published version, when the source is pinned to an older one. Null when it is current.

argumentsobject

The action's arguments, as stored: each value in its stored form. Send them back as they are, or as plain values. Null for merge and fixed sources.

optionsobject

The action's options, such as pagination. Null for merge and fixed sources.

queryobject

The filter and sort the app applies before the rows are stored: { filter, sort }. Null when there is none.

inputsarray of objects

For a merge source, the sources it combines. Null for other types.

  • dataSourceIdstring

    The input source, from List Analytics Data Sources.

  • aliasstring

    The name the merge SQL and code read this input by.

  • querystring

    The SQL that shapes this input, reading it as `src`. Empty when it is used as is.

transformCodestring

For a merge source, the code that combines its inputs. Null for other types.

fileobject

For a fixed source, the data it holds. Null for other types, or before any data is stored.

  • originstring

    Where the rows came from. rows: rows sent in a request; attachment: an uploaded file; tableEditor: an edit to the table.

    • rows
    • attachment
    • tableEditor
  • filenamestring

    The file's name, or the label given to rows sent in a request.

  • formatstring

    The file format, such as csv, xlsx or json.

  • mimeTypestring

    The file's media type.

  • sizeBytesnumber

    The size of the stored data in bytes.

  • uploadedOndate

    When the data was stored.

  • rowCountnumber

    How many rows the data holds.

  • sheetNamestring

    For a spreadsheet, the sheet the rows are read from.

  • useHeaderboolean

    For a spreadsheet, whether its first row holds the column names.

  • removeTopRowsnumber

    For a spreadsheet, how many rows above the header are skipped.

dateKeysobject

Which columns hold dates, for page date filters. Null until they are known.

  • primaryDateKeystring

    The column page date filters use for this source.

  • primaryDateKeyGrainstring

    The primary date column's grain: day for dates, timestamp for dates with times.

  • createdDateKeystring

    The column holding when each record was created.

  • updatedDateKeystring

    The column holding when each record last changed.

  • hasNoDatesboolean

    True when the source has no date column.

isIncrementalActiveboolean

For a sync source, whether incremental refreshes actually run: switched on, and the source can fetch only changed records. Null for other types.

incrementalobject

For a sync source, how it fetches only changed records. Null when that was never set up.

  • statusstring

    Whether this source can fetch only changed records. active: it can; unavailable: it cannot.

    • active
    • unavailable
  • dedupKeyarray

    The field paths that identify a record, used to replace changed records.

  • sinceArgumentsobject

    The extra action arguments that ask the app for records changed since the last check.

  • catchesstring

    What the change check finds. newAndChanged: new and edited records; newOnly: new records only.

    • newAndChanged
    • newOnly
  • overlapSecondsnumber

    How far back before the last check each check looks, in seconds.

  • reasonstring

    Why changed records cannot be fetched, when status is unavailable.

  • checkedOndate

    When these details were last checked against the source.

coverageobject

For a sync source, how much time its stored rows span. Null when not measured.

  • codestring

    The coverage verdict, such as COVERED, TRUNCATED or FILTER_NOT_APPLIED.

  • levelstring

    How the verdict reads: ok, info or warn.

    • ok
    • info
    • warn
  • messagestring

    The verdict in words.

  • coverageFromdate

    The earliest record date the data holds.

  • coverageTodate

    The latest record date the data holds.