--- title: "List Agent Trace Plans" method: GET path: "/internal/agent-traces/plans/{thread_id}" --- # List Agent Trace Plans `GET /internal/agent-traces/plans/{thread_id}` ## Request - Base URL: `https://app.runconverge.com/api` - URL: `https://app.runconverge.com/api/internal/agent-traces/plans/{thread_id}` - Auth: none declared All plans (with outcomes) tied to a LangSmith thread. `thread_id` maps to `agent_sessions.sdk_session_id`. Plans are joined via `agent_session_id`; outcomes are eager-loaded so the response carries the full audit trail in one round-trip. ## Path parameters - `thread_id` string, required ## Headers - `Authorization` string, nullable ## Cookies - `session_id` string, nullable ## Response `200` Successful Response - AgentTraceSessionPlansResponse - `thread_id` string, required - `plans` AgentTracePlan[], required - `id` integer, required - `version` integer, required - `status` 'active' | 'applied' | 'partially_applied' | 'superseded' | 'canceled', required - `created_at` string, date-time, required - `updated_at` string, date-time, required - `payload` Plan, required - `id` string, required - `title` string, nullable - `estimated_impact` string[], required - `suggestions` ConvergeApiPlanSchemaSuggestion[], required - `id` string, required: Unique within the plan. - `action` 'scale-up' | 'scale-down' | 'pause' | 'activate' | 'bid' | 'rename' | 'duplicate-ad' | 'duplicate-adset' | 'duplicate-campaign' | 'landing-url', required - `platform` 'meta', required - `primary_target` ChangeTarget, required - `scope` 'campaign' | 'adset' | 'ad', required - `platform_object_id` string, required - `name` string, required - `campaign_id` string, nullable - `campaign_name` string, nullable - `adset_id` string, nullable - `adset_name` string, nullable - `summary` string, required - `rationale` string, required - `reasons` Evidence[], required - `text` string, required - `polarity` 'positive' | 'negative' | 'neutral', required - `confidence` number, required - `impact` number, required - `viz` Viz, required: How the FE should render data behind a Suggestion. The agent declares *which* metrics to query and *how* (date range, granularity, attribution); the FE issues the insight query and renders cards/sparkline from the result. The agent never embeds pre-computed values. - `primary_metric` union, required - EventMetricSpec - … - MarketingMetricSpec - … - `supporting_metrics` union[] - union - … - `since` string, date, required - `until` string, date, required - `time_granularity` 'hour' | 'day' | 'week' | 'month', required - `attribution` ConvergeApiPlanSchemaAttribution - `model` 'direct_session' | 'first_touch' | 'first_touch_paid' | 'inv_j_shaped' | 'inv_j_shaped_paid' | 'j_shaped' | 'j_shaped_paid' | 'last_touch' | 'last_touch_paid' | 'linear' | 'top_of_funnel' | 'participation' | 'u_shaped' | 'time_decay' | 'inv_time_decay', required - `window` integer, required - `mode` 'click_time' | 'conversion_time', required - `changes` union[], required - union - DailyBudgetChange - … - LifetimeBudgetChange - … - DailySpendCapChange - … - LifetimeSpendCapChange - … - BidAmountChange: Ad set bid/cost goal (`bid_amount`), in the account's major units. Backs Meta's `LOWEST_COST_WITH_BID_CAP` (bid cap) and `COST_CAP` (cost-per-result goal) bid strategies — both store their target in the ad-set-level `bid_amount` field, so a single change variant covers both. - … - RoasGoalChange: Ad set minimum-ROAS goal for the `LOWEST_COST_WITH_MIN_ROAS` strategy. - … - StatusChange - … - NameChange - … - LandingUrlChange: Change an ad's landing page URL — the destination "Website URL". Applied by minting a new creative from the source's spec with the link replaced (or rebuilt from the post a post-ID ad wraps), then pointing the ad at it. The new creative gets a new page post, so accumulated social proof (likes, comments) does not carry. - … - DuplicateAdChange: Duplicate an existing ad into another adset reusing the source ad's creative - … - DuplicateAdsetChange: Duplicate an existing ad set — its settings and its ads. Applied by *recreating* the ad set (Meta's `/copies` can only name the copy via prefix/suffix, and name-based URL parameters freeze at first publish, so the copy must be created bearing its final name). The child ads are then duplicated into the copy reusing each source ad's creative, so post IDs carry over; the ads keep their source names and statuses. - … - DuplicateCampaignChange: Duplicate an existing campaign — its settings, ad sets, and ads. Applied by *recreating* the whole tree (see `DuplicateAdsetChange` for why `/copies` can't be used): the campaign is created bearing its final name, each ad set is recreated into it keeping its own name and status, and each ad is duplicated reusing the source ad's creative so post IDs carry over. - … - `outcomes` AgentTracePlanOutcome[], required - `suggestion_id` string, required - `decision` 'accepted' | 'rejected' | 'skipped', required: The user's verdict on a single suggestion at apply time. - `success` boolean, nullable, required - `error` string, nullable, required - `created_at` string, date-time, required ## Other responses - `422`: Validation Error ## Changes - **2026-10-02** `da98d7824f8c`: 1 warning - added the new `neutral` enum value to the `plans/items/payload/suggestions/items/reasons/items/polarity` response property for the response status `200` - **2026-09-29** `31dc8dde8194`: 4 breaking - response property `plans/items/payload/suggestions/items/changes/items/oneOf[subschema #3: DailySpendCapChange]/from_amount` list-of-types was widened by adding types `null` to media type `application/json` of response `200` - response property `plans/items/payload/suggestions/items/changes/items/oneOf[subschema #3: DailySpendCapChange]/to_amount` list-of-types was widened by adding types `null` to media type `application/json` of response `200` - response property `plans/items/payload/suggestions/items/changes/items/oneOf[subschema #4: LifetimeSpendCapChange]/from_amount` list-of-types was widened by adding types `null` to media type `application/json` of response `200` - response property `plans/items/payload/suggestions/items/changes/items/oneOf[subschema #4: LifetimeSpendCapChange]/to_amount` list-of-types was widened by adding types `null` to media type `application/json` of response `200` - **2026-09-25** `7647ff1bd58b`: 1 info - removed the `follow_up` enum value from the `plans/items/outcomes/items/decision` response property for the response status `200` - …earlier changes not shown [Operation history](https://skmtc.dev/runconverge/apis/runconverge-api/changes/internal/agent-traces/plans/:thread_id/get.md) --- [API](https://skmtc.dev/runconverge/apis/runconverge-api.md) - [All operations](https://skmtc.dev/runconverge/apis/runconverge-api/llms.txt) - [OpenAPI document](https://skmtc.dev/runconverge/apis/runconverge-api/revisions/f723e951cc0b?raw)