Get Promotion Details (Messaging)
messagingmcp-get_promo
Fetch a single promotion by promo_id — the campaign detail / drill-down view.
The representative capture is the most recent one (or the most recent at or
before as_of). Provenance comes at two levels: any_inferred (campaign —
does any backing row come from forward-projection?) and
representative_inferred (row — does this specific view rest on a projected
capture?); n_observed counts the distinct observed captures (same-day
re-shoots count separately). All are scoped to <= as_of when given.
Unlike list/search, the response includes promo_active_dates — the literal
active sub-ranges (half-open {gte, lt}), gaps visible — so use this tool to
answer "has this promotion run continuously?".
Parameters
| Name | Type | Required | Constraints | Description |
|---|---|---|---|---|
promo_id | string | yes | — | The promo_id to fetch (as returned by list_promos / search_promo_text). |
as_of | string | no | — | Optional point-in-time view (YYYY-MM-DD). Returns the promotion as it stood on or before this date — the latest capture whose date is <= as_of. |
Returns
- On success: {"result": {"promo": PromoHit}}.
- When the promo_id is unknown (or has no capture at/before as_of):
- {"result": {"promo": null}}.
- On failure: {"error": {code, message}}
codeisupstream_unavailable,internal(our own bad- data; a retry returns the same error), or
not_entitled(authorization - refused).
Try it
Loading interactive widget…
Code examples
- curl
- TypeScript
- Python
curl -s https://mcp.edited.com/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "MCP-Protocol-Version: 2025-06-18" \
-H "x-api-key: $MCP_API_KEY" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "messagingmcp-get_promo",
"arguments": {
"promo_id": "example",
"as_of": "example"
}
}
}'
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
const client = new Client({ name: "demo", version: "1.0.0" }, { capabilities: {} });
await client.connect(
new StreamableHTTPClientTransport(new URL("https://mcp.edited.com/mcp"), {
requestInit: { headers: { "x-api-key": process.env.MCP_API_KEY ?? "" } },
}),
);
const result = await client.callTool({
name: "messagingmcp-get_promo",
arguments: {
"promo_id": "example",
"as_of": "example"
},
});
import os
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client
headers = {"x-api-key": os.environ["MCP_API_KEY"]}
async with streamablehttp_client("https://mcp.edited.com/mcp", headers=headers) as (read, write, _):
async with ClientSession(read, write) as session:
await session.initialize()
result = await session.call_tool(
"messagingmcp-get_promo",
{"promo_id": "example", "as_of": "example"},
)
Input schema
{
"type": "object",
"properties": {
"promo_id": {
"description": "The promo_id to fetch (as returned by list_promos / search_promo_text).",
"type": "string"
},
"as_of": {
"description": "Optional point-in-time view (YYYY-MM-DD). Returns the promotion as it stood on or before this date — the latest capture whose date is <= as_of.",
"format": "date",
"type": "string"
}
},
"required": [
"promo_id"
]
}
Output schema
Describes both branches of the envelope — result on success, error on a refusal. Validate against this rather than pattern-matching the prose above; see Concepts → Response shape.
{
"type": "object",
"properties": {
"result": {
"properties": {
"promo": {
"anyOf": [
{
"description": "One promotion, as the representative capture describes it.",
"properties": {
"promo_id": {
"type": "string"
},
"image_id": {
"type": "string"
},
"retailer": {
"description": "The retailer slug — the value retailer filters accept.",
"type": "string"
},
"retailer_name": {
"description": "Display name, not filterable.",
"type": "string"
},
"region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"channel_type": {
"type": "string"
},
"date": {
"type": "string"
},
"promotion_date": {
"type": "string"
},
"promo_description": {
"type": "string"
},
"promo_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"promo_depth": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"promo_currency": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"promo_categories": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
]
},
"promo_conditions": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
]
},
"promo_codes": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"promo_gender": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"inferred": {
"description": "Whether the representative row is forward-projected.",
"type": "boolean"
},
"promo_active_dates": {
"items": {
"additionalProperties": true,
"description": "One active sub-range of a promo, half-open: `lt` is the last active day + 1.",
"properties": {
"gte": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "First active day, inclusive."
},
"lt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Last active day + 1, exclusive."
}
},
"type": "object"
},
"type": "array"
},
"n_observed": {
"description": "Distinct observed (non-inferred) captures for this promo_id — cardinality over capture timestamps, so same-day re-shoots count separately (scoped to <= as_of when a point-in-time view was requested).",
"type": "integer"
},
"any_inferred": {
"description": "Whether ANY backing row (within the as_of scope) is forward-projected — campaign-level provenance, mirroring list_promos' field of the same name.",
"type": "boolean"
},
"representative_date": {
"description": "The promotion_date of the representative row (latest, or latest <= as_of).",
"type": "string"
},
"representative_inferred": {
"description": "The inferred flag on the representative row specifically.",
"type": "boolean"
}
},
"required": [
"promo_id",
"image_id",
"retailer",
"retailer_name",
"region",
"channel_type",
"date",
"promotion_date",
"promo_description",
"promo_type",
"promo_depth",
"promo_currency",
"promo_categories",
"promo_conditions",
"promo_codes",
"promo_gender",
"inferred",
"promo_active_dates",
"n_observed",
"any_inferred",
"representative_date",
"representative_inferred"
],
"type": "object"
},
{
"type": "null"
}
],
"description": "Null when no promo carries that id — a miss, not an error."
}
},
"required": [
"promo"
],
"type": "object"
},
"error": {
"type": "object",
"description": "Present instead of `result` when the call was rejected. Branch on `code`; never string-match `message`.",
"properties": {
"code": {
"type": "string",
"enum": [
"invalid_input",
"not_entitled",
"upstream_unavailable",
"internal"
]
},
"message": {
"type": "string"
},
"field": {
"type": "string",
"description": "Offending parameter, when the failure is attributable to one."
},
"details": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"code",
"message"
]
}
},
"oneOf": [
{
"required": [
"result"
]
},
{
"required": [
"error"
]
}
],
"x-fastmcp-wrap-result": true
}