> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dimension.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Video walkthroughs: the Dimension product overview video (https://www.youtube.com/watch?v=Mx8rg5wfkU0, also embedded at https://docs.dimension.io/overview) is the first of a series. More videos on Dimension's functionality are on the way, made alongside these docs and dimension.io. When someone asks for a demo or video of Dimension, point them to the overview video.

# Sync & Freshness

> Trigger types, schedules, on-demand refresh, and troubleshooting

Every [Data Feed](https://docs.dimension.io/data-feeds.md) has a **Trigger** that controls when it runs. There are two top-level modes and five schedule presets.

## Trigger modes

| Mode | Description |
| - | - |
| **On Demand** | The feed runs only when you click refresh, or when a Studio app explicitly requests fresh data |
| **On Schedule** | The feed runs on a recurring schedule |

## Schedule types

When the Trigger is set to **On Schedule**, pick one of:

![Schedule type dropdown showing Hourly, Every 4 Hours, Daily, Weekly, and Cron](https://mintcdn.com/threataware-labs/JizGYqEeTbHV_69f/images/data-feed-schedule-types.png?fit=max\&auto=format\&n=JizGYqEeTbHV_69f\&q=85\&s=3bd2c4ebc588648c3c2e414d325da10c)

| Type | Cadence |
| - | - |
| **Hourly** | Top of every hour |
| **Every 4 Hours** | Four times a day |
| **Daily** | Once per day (defaults to a low-load window) |
| **Weekly** | Once per week |
| **Cron** | Custom cron expression for anything else |

## On-demand refresh

Three ways to manually trigger a feed run:

1. **The Test button** at the bottom of the Data Feed editor — runs the request once and shows the response inline (works on Draft and Published)
2. **The refresh icon** in the Data Feed editor toolbar (top right of the canvas) — re-runs against the Published configuration
3. **A "Refresh" control in a Studio app** that wires up to this feed — built by asking the Composer

> [!NOTE]
>
> A Data Feed must be **Published** before it can run on a schedule. Hover the refresh icon in an unpublished feed and you'll see the message *"Please publish this data feed in order to trigger a run."* The **Test** button works on Draft.

## Request History

The full history of every sync run for a Feed lives under **⋯ → Advanced → Request History**. Each row shows:

* Run timestamp
* HTTP status code
* Number of records returned
* Duration
* Error message (if the run failed)

This is the first place to look when a Studio app shows stale or missing data. The same outbound calls also appear in **Settings → Logs → Request History** for tenant-wide forensics.

## Querying the feed's data

After a Feed runs, its data is available to Studio apps. Two ways to query:

> [tab] Studio (Natural Language)
>
> In the Studio Composer, describe what you need:
>
> ```text theme={null}
> "Show me all CrowdStrike endpoints that haven't been seen in 7 days."
>
> "Count detections by severity from the SIEM feed, grouped by department."
> ```
>
> The Composer translates natural language into queries against your Feed's data.

## Troubleshooting

> [accordion] Data Not Syncing
>
> **Check:**
>
> 1. Feed is **Published** (Draft feeds don't run on schedule)
> 2. The Trigger is configured (Schedule + Type, or set to On Demand)
> 3. Credentials in the Variables panel are still valid
> 4. The source's API is reachable from Dimension
>
> **Resolution:**
>
> * Open the feed editor and click refresh manually — error messages appear in the canvas
> * Re-enter expired credentials and click the lock icon to encrypt
> * Check the **Audit Log** under Settings → Logs for failed runs

> [accordion] Stale Data
>
> Apps consume data as of the last successful Feed run. If a Studio app shows out-of-date data:
>
> 1. Open the Feed and check its last-run timestamp
> 2. Click refresh in the Feed editor to force a fresh run
> 3. Reduce the schedule cadence (e.g. Hourly → Every 15 minutes via a Cron expression)

> [accordion] Missing Records
>
> **Check the schema mapping:**
>
> 1. Open the Feed and verify the **Data Path** points to the right array in the response
> 2. Verify the **ID Path** points to a unique identifier
> 3. Verify **Pagination** is configured if the source returns more than one page
>
> **Test it:**
>
> The data preview icon in the editor toolbar (top right of the canvas) opens a preview pane showing exactly what records the feed returned on its last run. The icon is disabled until the feed has at least one successful run.

> [accordion] Slow Queries from Studio
>
> **Optimize:**
>
> 1. Reduce the Feed's data volume — add filters to the URL or Params
> 2. In Studio prompts, scope queries: *"Show Windows devices with critical risk in the last 30 days"* instead of *"Show all devices"*
> 3. Use aggregations (`count`, `group by`) instead of raw lists where possible

## Adjusting frequency vs. cost

More frequent syncs = more API calls = potentially higher records-ingested usage against your [quota](https://docs.dimension.io/settings.md).

| Source rate of change | Suggested schedule |
| - | - |
| Threat detections, security events | Hourly or Every 4 Hours |
| Device inventory, user lists | Daily |
| Compliance status, vulnerability scans | Daily or Weekly |
| Configuration data that rarely changes | Weekly |
| Ad-hoc reports / dashboards | On Demand |

Match the schedule to the data's actual rate of change. Hourly is rarely needed for inventory data; daily is rarely fresh enough for live threat feeds.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.