---
title: "Refresh a Source"
method: POST
path: "/v25-10-beta/agentic-logic/sources/{name}/refresh"
tags: ["Agentic Logic"]
---

# Refresh a Source

`POST /v25-10-beta/agentic-logic/sources/{name}/refresh`

## Request

- Base URL: `https://api.intelligems.io`
- URL: `https://api.intelligems.io/v25-10-beta/agentic-logic/sources/{name}/refresh`
- Auth: API key in header `intelligems-access-token`
- TypeScript: <https://skmtc.dev/intelligems/apis/intelligems-external-api-v25-10-beta/docs/v25-10-beta/agentic-logic/sources/:name/refresh/post.ts> (a function with typed inputs; its response is checked against the schema)

```http
POST /v25-10-beta/agentic-logic/sources/{name}/refresh
```

Queues a refresh of the Source's cached data. It spends the shop's Admin API
read budget, so it is refused (with a reason) while the budget has no headroom,
during a per-Source cooldown, or when a refresh is already in flight.

Use the `intelligems-access-token` header. The token selects the organization; do not send `orgId`. The organization must have Agentic Logic enabled.

**Rate Limit:** 50 requests per 30s window, refilling 25 tokens every 30s.

## Path parameters

- `name` string, required

## Response `200`

OK

- union
  - object
    - `source` object, required: One Source: a named, org-scoped read definition whose answer the platform keeps cached and refreshed. Rules read it with sdk.getSource(name), or sdk.getSourceRaw(name) for a GraphQL or script Source.
      - `name` string, required: The Source's stable lower-kebab name — what rule code passes to sdk.getSource(name) (sdk.getSourceRaw(name) for a GraphQL Source). Never renamed once rules ship against it.
      - `description` string, required: What the Source reads and what rules use it for — the text an agent reads to judge reuse.
      - `definition` union, required: The typed read the Source names.
        - object
          - `kind` 'bestSellers', required
          - `args` object, required
            - `timeWindow` '24h' | '7d' | '30d' | '90d': '24h' | '7d' | '30d' | '90d' trailing window (default '30d').
            - `metric` 'units' | 'revenue': 'units' (default, net items sold) or 'revenue' (net sales) — what the ranking orders by.
            - `scope` object: Collections and/or tags to restrict the ranking to. Tag scope narrows the ranking itself; collection scope filters the ranked products, so a tight collection can return fewer than `limit`.
              - …
            - `limit` integer, required: Products to return, in rank order (max 250).
            - `excludeOutOfStock` boolean: Drop products with no variant available for sale. Applied after ranking, so the list can shrink below `limit`.
        - object
          - `kind` 'newArrivals', required
          - `args` object, required
            - `timeWindow` '24h' | '7d' | '30d' | '90d': '24h' | '7d' | '30d' | '90d' trailing window (default '30d').
            - `dateField` 'created' | 'published': 'created' (default) uses the product's creation date; 'published' uses the date it went live on the Online Store.
            - `scope` object: Collections and/or tags to restrict the read to.
              - …
            - `limit` integer, required: Products to return, newest first (max 250).
            - `excludeOutOfStock` boolean: Drop products with no variant available for sale. Applied after the read, so the list can shrink below `limit`.
        - object
          - `kind` 'inStock', required
          - `args` object, required
            - `minQuantity` integer: Minimum total inventory quantity, inclusive (default 1).
            - `scope` object: Collections and/or tags to restrict the read to.
              - …
            - `orderBy` object: Sort. Default is highest inventory first ('inventoryTotal' desc); 'price' and 'bestSelling' only sort server-side inside exactly one collection.
              - …
            - `limit` integer, required: Products to return (max 250).
        - object
          - `kind` 'collectionProducts', required
          - `args` object, required
            - `orderBy` object: Server-side sort.
              - …
            - `limit` integer, required: Maximum products to return. Positive integer, max 250 per read; postFetch queries may scan more than they return (see scan).
            - `include` object: Extra per-product data to fetch (explicit metafield refs).
              - …
            - `collectionId` string, required: Scope the query to one collection (gid://shopify/Collection/<n>, or the bare numeric id the Shopify admin shows). Required for where.server.productFilters. Cannot be combined with ids.
        - object
          - `kind` 'storefrontGraphql', required
          - `args` object, required
            - `gql` string, required
            - `variables` object, required
        - object
          - `kind` 'adminGraphql', required
          - `args` object, required
            - `gql` string, required
            - `variables` object, required
        - object
          - `kind` 'script', required
          - `args` object, required
            - `workspace` object, required
              - …
            - `outputSchema` object
      - `summary` string, required: One human-readable line describing the read.
      - `freshMs` integer, required: How long a fetched answer counts as fresh, in ms: the override when set, else the read kind's default. The scheduled refresh runs at about 80% of it.
      - `freshMsOverride` integer, nullable, required: The Source's own freshness in ms, shorter or longer than the read kind's default (1 minute to 24 hours for a read; 15 minutes to 7 days for a script); null when the Source follows the default.
      - `status` 'warming' | 'ready' | 'stale' | 'error', required: warming (never fetched), ready (fresh), stale (older than freshMs, still served while it refreshes) or error (the last refresh failed).
      - `fetchedAt` number, nullable, required: When the cached answer was fetched, epoch ms; null when nothing is cached.
      - `lastRefreshedAt` number, nullable, required: When the last scheduled or requested refresh finished, epoch ms; null when none has run.
      - `lastRefreshStatus` 'ok' | 'error', nullable, required: Outcome of the last scheduled or requested refresh; null when none has run.
      - `lastError` string, nullable, required: Why the last refresh failed; null after a successful refresh.
      - `lastBuildLog` string, nullable, required: The console output of a script Source's last build (its tail, at most 8 KiB), whether it succeeded or failed; null for other kinds and before the first build.
      - `lastReadAt` number, nullable, required: When a rule last read the Source, epoch ms (recorded at most every 10 minutes); null when never read. Sources idle for 7 days stop refreshing.
      - `lastUpdateTs` number, required: When the Source definition was last written, epoch ms.
    - `queued` true, required
  - object
    - `source` object, required: One Source: a named, org-scoped read definition whose answer the platform keeps cached and refreshed. Rules read it with sdk.getSource(name), or sdk.getSourceRaw(name) for a GraphQL or script Source.
      - `name` string, required: The Source's stable lower-kebab name — what rule code passes to sdk.getSource(name) (sdk.getSourceRaw(name) for a GraphQL Source). Never renamed once rules ship against it.
      - `description` string, required: What the Source reads and what rules use it for — the text an agent reads to judge reuse.
      - `definition` union, required: The typed read the Source names.
        - object
          - `kind` 'bestSellers', required
          - `args` object, required
            - `timeWindow` '24h' | '7d' | '30d' | '90d': '24h' | '7d' | '30d' | '90d' trailing window (default '30d').
            - `metric` 'units' | 'revenue': 'units' (default, net items sold) or 'revenue' (net sales) — what the ranking orders by.
            - `scope` object: Collections and/or tags to restrict the ranking to. Tag scope narrows the ranking itself; collection scope filters the ranked products, so a tight collection can return fewer than `limit`.
              - …
            - `limit` integer, required: Products to return, in rank order (max 250).
            - `excludeOutOfStock` boolean: Drop products with no variant available for sale. Applied after ranking, so the list can shrink below `limit`.
        - object
          - `kind` 'newArrivals', required
          - `args` object, required
            - `timeWindow` '24h' | '7d' | '30d' | '90d': '24h' | '7d' | '30d' | '90d' trailing window (default '30d').
            - `dateField` 'created' | 'published': 'created' (default) uses the product's creation date; 'published' uses the date it went live on the Online Store.
            - `scope` object: Collections and/or tags to restrict the read to.
              - …
            - `limit` integer, required: Products to return, newest first (max 250).
            - `excludeOutOfStock` boolean: Drop products with no variant available for sale. Applied after the read, so the list can shrink below `limit`.
        - object
          - `kind` 'inStock', required
          - `args` object, required
            - `minQuantity` integer: Minimum total inventory quantity, inclusive (default 1).
            - `scope` object: Collections and/or tags to restrict the read to.
              - …
            - `orderBy` object: Sort. Default is highest inventory first ('inventoryTotal' desc); 'price' and 'bestSelling' only sort server-side inside exactly one collection.
              - …
            - `limit` integer, required: Products to return (max 250).
        - object
          - `kind` 'collectionProducts', required
          - `args` object, required
            - `orderBy` object: Server-side sort.
              - …
            - `limit` integer, required: Maximum products to return. Positive integer, max 250 per read; postFetch queries may scan more than they return (see scan).
            - `include` object: Extra per-product data to fetch (explicit metafield refs).
              - …
            - `collectionId` string, required: Scope the query to one collection (gid://shopify/Collection/<n>, or the bare numeric id the Shopify admin shows). Required for where.server.productFilters. Cannot be combined with ids.
        - object
          - `kind` 'storefrontGraphql', required
          - `args` object, required
            - `gql` string, required
            - `variables` object, required
        - object
          - `kind` 'adminGraphql', required
          - `args` object, required
            - `gql` string, required
            - `variables` object, required
        - object
          - `kind` 'script', required
          - `args` object, required
            - `workspace` object, required
              - …
            - `outputSchema` object
      - `summary` string, required: One human-readable line describing the read.
      - `freshMs` integer, required: How long a fetched answer counts as fresh, in ms: the override when set, else the read kind's default. The scheduled refresh runs at about 80% of it.
      - `freshMsOverride` integer, nullable, required: The Source's own freshness in ms, shorter or longer than the read kind's default (1 minute to 24 hours for a read; 15 minutes to 7 days for a script); null when the Source follows the default.
      - `status` 'warming' | 'ready' | 'stale' | 'error', required: warming (never fetched), ready (fresh), stale (older than freshMs, still served while it refreshes) or error (the last refresh failed).
      - `fetchedAt` number, nullable, required: When the cached answer was fetched, epoch ms; null when nothing is cached.
      - `lastRefreshedAt` number, nullable, required: When the last scheduled or requested refresh finished, epoch ms; null when none has run.
      - `lastRefreshStatus` 'ok' | 'error', nullable, required: Outcome of the last scheduled or requested refresh; null when none has run.
      - `lastError` string, nullable, required: Why the last refresh failed; null after a successful refresh.
      - `lastBuildLog` string, nullable, required: The console output of a script Source's last build (its tail, at most 8 KiB), whether it succeeded or failed; null for other kinds and before the first build.
      - `lastReadAt` number, nullable, required: When a rule last read the Source, epoch ms (recorded at most every 10 minutes); null when never read. Sources idle for 7 days stop refreshing.
      - `lastUpdateTs` number, required: When the Source definition was last written, epoch ms.
    - `queued` false, required
    - `notQueuedReason` 'in_flight' | 'no_market' | 'admin_budget' | 'cooldown', required

## Other responses

- `429`: Too Many Requests

---

[API](https://skmtc.dev/intelligems/apis/intelligems-external-api-v25-10-beta.md) - [All operations](https://skmtc.dev/intelligems/apis/intelligems-external-api-v25-10-beta/llms.txt) - [OpenAPI document](https://skmtc.dev/intelligems/apis/intelligems-external-api-v25-10-beta/revisions/7b769b2f90b1?raw)