Sugra API

get_timeseries

Read-onlyIdempotent

Bounded timeseries for an entity: price, macro_series, etf_flows or etf_monthly_flows.

Returns points oldest-first with an explicit downsampling flag when the raw series exceeded max_points. Times are UTC. Costs 1 unit per call.

Read the step from served_granularity, not granularity. The latter echoes the request; the former is the step the source built the points at, and the two can differ (a long price range can come back as monthly bars under a "1d" request). It reads mixed when the points do not share one step, unknown when the source does not say, and null when no point came back. It describes how each point was built, not how far apart the returned points are: a thinned daily series still reads 1d, and downsampled is what says points were dropped.

The two ETF flow metrics answer different questions and are not interchangeable. etf_flows is an ESTIMATE at filing cadence: one point per SEC filing refresh, so t is a filing date and even a wide window yields a handful of points. etf_monthly_flows is the fund's own creations and redemptions from its NPORT-P filing, so t is a calendar month (YYYY-MM) and each point carries the three filed components - sales, reinvestment, redemption - beside the net.

Two things to read before quoting etf_monthly_flows. NPORT-P is filed per SERIES, so for a fund with more than one share class the figures cover every class and the payload says so in multi_class_series; where the class count is unknown it says class_scope instead of staying silent. And a fund that files no NPORT-P at all, such as a commodity trust, is not an error: the call returns status partial with an empty point list and a reason.

Args: metric: One of price / macro_series / etf_flows / etf_monthly_flows. entity: Entity dict from resolve_entity ({"namespace": ..., "ids": ...}). granularity: Requested point granularity (default "1d"). max_points: Hard cap on returned points (default 500).

Input Schema

Name	Required	Description	Default
`entity`	Yes	Entity dict from resolve_entity ({namespace, ids}). Extra keys are ignored.
`metric`	Yes
`max_points`	No
`granularity`	No		1d

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed7 schema fields changedSep 14, 2026

removedInput schema / $defs

Removed value: -{
-  "AgentEntity": {
-    "description": "The agent-plane entity shape returned by resolve_entity and consumed by\nget_snapshot / get_timeseries. Extra keys from a resolve result (label,\nconfidence) are accepted and ignored - only namespace + ids are sent on.",
-    "properties": {
-      "ids": {
-        "additionalProperties": true,
-        "title": "Ids",
-        "type": "object"
-      },
-      "namespace": {
-        "title": "Namespace",
-        "type": "string"
-      }
-    },
-    "required": [
-      "namespace",
-      "ids"
-    ],
-    "title": "AgentEntity",
-    "type": "object"
-  }
-}

removedInput schema / properties / entity / $ref
```
Removed value: -"#/$defs/AgentEntity"
```
addedInput schema / properties / entity / additionalProperties
```
Added value: +true
```

addedInput schema / properties / entity / description

Added value: +"Entity dict from resolve_entity ({namespace, ids}). Extra keys are ignored."

addedInput schema / properties / entity / properties

Added value: +{
+  "ids": {
+    "additionalProperties": true,
+    "description": "Identifier map from resolve_entity.",
+    "type": "object"
+  },
+  "namespace": {
+    "description": "Entity namespace from resolve_entity.",
+    "type": "string"
+  }
+}

addedInput schema / properties / entity / required
```
Added value: +[
+  "namespace",
+  "ids"
+]
```
addedInput schema / properties / entity / type
```
Added value: +"object"
```

Changed1 schema field changedSep 4, 2026

changedInput schema / properties / metric / enum

Previous value: -[
-  "price",
-  "macro_series",
-  "etf_flows"
-]New value: +[
+  "price",
+  "macro_series",
+  "etf_flows",
+  "etf_monthly_flows"
+]

Changed6 schema fields changedJul 5, 2026

addedInput schema / $defs

Added value: +{
+  "AgentEntity": {
+    "description": "The agent-plane entity shape returned by resolve_entity and consumed by\nget_snapshot / get_timeseries. Extra keys from a resolve result (label,\nconfidence) are accepted and ignored - only namespace + ids are sent on.",
+    "properties": {
+      "ids": {
+        "additionalProperties": true,
+        "title": "Ids",
+        "type": "object"
+      },
+      "namespace": {
+        "title": "Namespace",
+        "type": "string"
+      }
+    },
+    "required": [
+      "namespace",
+      "ids"
+    ],
+    "title": "AgentEntity",
+    "type": "object"
+  }
+}

addedInput schema / properties / entity / $ref
```
Added value: +"#/$defs/AgentEntity"
```
removedInput schema / properties / entity / additionalProperties
```
Removed value: -true
```
removedInput schema / properties / entity / title
```
Removed value: -"Entity"
```
removedInput schema / properties / entity / type
```
Removed value: -"object"
```

addedInput schema / properties / metric / enum

Added value: +[
+  "price",
+  "macro_series",
+  "etf_flows"
+]

First observedJun 22, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds a lot beyond them: cost of 1 unit per call, oldest-first ordering, UTC times, the downsampling flag when max_points is exceeded, and the partial-status-with-reason behavior for funds that file no NPORT-P. This is genuinely useful operational context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and metric list, and most paragraphs carry non-redundant information about edge cases. It is on the long side and revisits the granularity-vs-served_granularity distinction more than once, which costs it a point.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, yet the description still supplies the interpretation an agent needs for the trickiest return field (served_granularity reading 'mixed'/'unknown'/null, and why a thinned daily series still reads '1d'). Combined with the partial-status caveat, nothing needed to call this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 25%, so the description must compensate, and it does: it explains that granularity is a request hint that can differ from the served step (a '1d' request can return monthly bars), that max_points is a hard cap triggering the downsampling flag, and that entity comes from resolve_entity. The Args block itself largely restates the enum and defaults, hence not a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a precise verb+resource ('Bounded timeseries for an entity') and immediately enumerates the four metric domains it covers, which lets an agent distinguish it from get_snapshot or fetch_data without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives strong in-tool routing guidance — it states the two ETF metrics 'answer different questions and are not interchangeable' and tells the agent to read served_granularity rather than granularity. It does not, however, say when to prefer this tool over sibling alternatives like get_snapshot, so there is no cross-tool exclusion.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Sugra API tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.