AdCP 3.1.13 · Signals

get_signals

get_signals request fields

The required column reflects the top-level required array only. The request schema declares no required array, so none of the 18 request fields carries a top-level required flag. A top-level if, anyOf, oneOf or dependencies block can make an unmarked field mandatory in the mode being called, and a flat table cannot render a rule that fires in one mode only. Those branches are visible in the request schema itself.

get_signals reads. 30 of the 64 registered operations are flagged x-mutates-state and its request schema is not one of them, so repeating the call is side-effect free. AdCP's release notes describe x-mutates-state as a non-normative tooling hint that agents do not validate, so it is the registry's classification of the operation rather than a contract, and it is the only machine-readable answer in the registry to whether an operation is safe to retry.

get_signals response fields

The first 13 rows are the shared protocol envelope from core/version-envelope.json and core/protocol-envelope.json. Only 10 of the 23 rows below belong to get_signals itself, beginning with signals, errors and incomplete. One field in the whole response is marked required: status.

The shared protocol envelope

62 of AdCP's 64 registered operations carry every one of the 13 envelope fields. report_plan_outcome and check_governance compose core/version-envelope.json only, so they carry the version pair and none of the task fields.

status resolves to enums/task-status.json, which admits nine values: submitted, working, input-required, completed, canceled, failed, rejected, auth-required, unknown. The envelope marks it required on every response, and a synchronous call emits completed rather than omitting it. When it returns submitted or working instead, task_id is the polling handle and push_notification_config is the webhook the agent echoes back to confirm the callback. Webhooks are A2A and REST only: MCP sends progress notifications and defines no webhook.

payload appears in the response field table typed object. core/protocol-envelope.json describes it as a documentary construct and states that it is not a required wire field. Body fields are siblings of the envelope fields: on MCP at the root of the tool response, on A2A in task.artifacts[0].parts[].DataPart, on REST at the root of the JSON body. An accessor that reads response.payload finds nothing there.

Field lists are not published over the wire

AdCP's integration guide, docs/protocol/calling-an-agent.mdx, states that its MCP servers no longer publish per-tool parameter schemas: a tools/list call returns an empty properties object for every tool, and the guide directs clients not to infer shape from it. A client author reads the schema registry instead of the tool list.

Example get_signals calls

The field tables above come from the 3.1.13 schema release and these blocks come from the documentation tree, which is versioned separately, so the two can disagree.

{
  "signals": [
    {
      "signal_ref": {
        "scope": "data_provider",
        "data_provider_domain": "string",
        "signal_id": "string"
      },
      "signal_agent_segment_id": "string",
      "name": "string",
      "description": "string",
      "signal_type": "string",
      "data_provider": "string",
      "coverage_percentage": "number (optional, deprecated)",
      "coverage_forecast": {
        "method": "estimate",
        "forecast_range_unit": "availability",
        "scope": {
          "kind": "inventory",
          "label": "network price-priority inventory"
        },
        "bucket_semantics": "exclusive",
        "bucket_completeness": "partial",
        "points": [
          {
            "label": "not present",
            "dimensions": [
              {
                "kind": "signal",
                "signal_ref": {
                  "scope": "data_provider",
                  "data_provider_domain": "weather-data.example",
                  "signal_id": "weather"
                },
                "signal_value": null,
                "presence": "absent"
              }
            ],
            "metrics": {
              "impressions": { "mid": 280000 },
              "coverage_rate": { "mid": 0.28 }
            }
          },
          {
            "label": "hot",
            "dimensions": [
              {
                "kind": "signal",
                "signal_ref": {
                  "scope": "data_provider",
                  "data_provider_domain": "weather-data.example",
                  "signal_id": "weather"
                },
                "signal_value": "hot",
                "presence": "present"
              }
            ],
            "metrics": {
              "impressions": { "mid": 180000 },
              "coverage_rate": { "mid": 0.18 }
            }
          }
        ]
      },
      "deployments": [
        {
          "type": "agent",
          "agent_url": "string",
          "account": "string",
          "is_live": "boolean",
          "activation_key": {
            "type": "segment_id",
            "segment_id": "string"
          },
          "estimated_activation_duration_minutes": "number"
        }
      ],
      "pricing_options": [
        {
          "pricing_option_id": "string",
          "model": "cpm | percent_of_media | flat_fee | per_unit | custom",
          "...": "..."
        }
      ]
    }
  ]
}

{
  "type": "segment_id",
  "segment_id": "ttd_segment_12345"
}

{
  "type": "key_value",
  "key": "audience_segment",
  "value": "luxury_auto_intenders"
}

Other operations in Signals

• activate_signal

Related

• The full Signals reference
• All 64 entries in the AdCP 3.1.13 registry
• Does AAMP have an equivalent operation?