Search mentions across media

GET /v1/mentions

Find where a person, company, product, or topic is mentioned in indexed videos and podcasts. For a person, set `is_appearance` to true to find media appearances, false for mentions by others, or omit it for both. Results include a description, source video, and available timestamps. Cursor-paginated, filtered by entity (`entity_id` is required; resolve a name first with GET /v1/entities/resolve, or the call answers 400 id_required naming the parameter), channel (`channel_id`), text query, sentiment, appearance flag, and publication window [after, before). The signed continuation binds the route, filters, caller and visibility; invalid or old cursors return invalid_cursor. A first-page ID fence excludes later insertions, including old-date backfills. Edits and deletions to existing mentions remain live. Positions are start_seconds and end_seconds (integer seconds; 0 means full episode). is_appearance filtering applies to person entities only; passing is_appearance=true for any other type returns a 400 (appearances_person_only). details=full attaches per-mention commercial recommendations and requires a Pro+ plan.

Parameters

Responses

{
  "description": "Success",
  "headers": {
    "X-Request-Id": {
      "$ref": "#/components/headers/X-Request-Id"
    },
    "X-Arcmira-Version": {
      "$ref": "#/components/headers/X-Arcmira-Version"
    },
    "RateLimit-Limit": {
      "$ref": "#/components/headers/RateLimit-Limit"
    },
    "RateLimit-Remaining": {
      "$ref": "#/components/headers/RateLimit-Remaining"
    },
    "RateLimit-Reset": {
      "$ref": "#/components/headers/RateLimit-Reset"
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/MentionListResponse"
      }
    }
  }
}

{
  "$ref": "#/components/responses/InvalidRequest"
}

{
  "$ref": "#/components/responses/AuthenticationError"
}

{
  "$ref": "#/components/responses/QuotaExceeded"
}

{
  "$ref": "#/components/responses/PermissionError"
}

{
  "$ref": "#/components/responses/NotFound"
}

{
  "$ref": "#/components/responses/RateLimited"
}

{
  "$ref": "#/components/responses/ServerError"
}

Operation definition

{
  "tags": [
    "Mentions"
  ],
  "operationId": "list_mentions",
  "summary": "Search mentions across media",
  "description": "Find where a person, company, product, or topic is mentioned in indexed videos and podcasts. For a person, set `is_appearance` to true to find media appearances, false for mentions by others, or omit it for both. Results include a description, source video, and available timestamps. Cursor-paginated, filtered by entity (`entity_id` is required; resolve a name first with GET /v1/entities/resolve, or the call answers 400 id_required naming the parameter), channel (`channel_id`), text query, sentiment, appearance flag, and publication window [after, before). The signed continuation binds the route, filters, caller and visibility; invalid or old cursors return invalid_cursor. A first-page ID fence excludes later insertions, including old-date backfills. Edits and deletions to existing mentions remain live. Positions are start_seconds and end_seconds (integer seconds; 0 means full episode). is_appearance filtering applies to person entities only; passing is_appearance=true for any other type returns a 400 (appearances_person_only). details=full attaches per-mention commercial recommendations and requires a Pro+ plan.",
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100,
        "default": 20
      },
      "required": false,
      "name": "limit",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "description": "Signed continuation from next_cursor. Bound to this route, normalized query, caller and visibility; invalid or old tokens return invalid_cursor."
      },
      "required": false,
      "description": "Signed continuation from next_cursor. Bound to this route, normalized query, caller and visibility; invalid or old tokens return invalid_cursor.",
      "name": "cursor",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "minLength": 1,
        "description": "The entity, as an id like ent_14. Required. Ids only: a name answers 400 id_required. Resolve names first with GET /v1/entities/resolve."
      },
      "required": true,
      "description": "The entity, as an id like ent_14. Required. Ids only: a name answers 400 id_required. Resolve names first with GET /v1/entities/resolve.",
      "name": "entity_id",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "description": "Only media from this YouTube channel id (UC plus 22 characters). Ids only: a name answers 400 id_required. Resolve names first with GET /v1/entities/resolve."
      },
      "required": false,
      "description": "Only media from this YouTube channel id (UC plus 22 characters). Ids only: a name answers 400 id_required. Resolve names first with GET /v1/entities/resolve.",
      "name": "channel_id",
      "in": "query"
    },
    {
      "schema": {
        "type": "string"
      },
      "required": false,
      "name": "q",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "enum": [
          "positive",
          "neutral",
          "negative"
        ]
      },
      "required": false,
      "name": "sentiment",
      "in": "query"
    },
    {
      "schema": {
        "type": "boolean"
      },
      "required": false,
      "name": "is_appearance",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "description": "Only media published at or after this instant. An ISO 8601 date (2026-09-01) or datetime with offset (2026-09-01T00:00:00Z), read in UTC. The window is half-open: after is inclusive, before is exclusive."
      },
      "required": false,
      "description": "Only media published at or after this instant. An ISO 8601 date (2026-09-01) or datetime with offset (2026-09-01T00:00:00Z), read in UTC. The window is half-open: after is inclusive, before is exclusive.",
      "name": "after",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "description": "Only media published before this instant, so before=2026-09-02 includes all of 2026-09-01. Needs a paid plan: the free plan refuses it with filter_requires_paid. An ISO 8601 date (2026-09-01) or datetime with offset (2026-09-01T00:00:00Z), read in UTC. The window is half-open: after is inclusive, before is exclusive."
      },
      "required": false,
      "description": "Only media published before this instant, so before=2026-09-02 includes all of 2026-09-01. Needs a paid plan: the free plan refuses it with filter_requires_paid. An ISO 8601 date (2026-09-01) or datetime with offset (2026-09-01T00:00:00Z), read in UTC. The window is half-open: after is inclusive, before is exclusive.",
      "name": "before",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "enum": [
          "full"
        ]
      },
      "required": false,
      "name": "details",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "enum": [
          "mcp-tool"
        ],
        "description": "The surface making this call. The Arcmira MCP server sends mcp-tool so every unlock link in a gate attributes to the directory install. Omit from your own client."
      },
      "required": false,
      "description": "The surface making this call. The Arcmira MCP server sends mcp-tool so every unlock link in a gate attributes to the directory install. Omit from your own client.",
      "name": "src",
      "in": "query"
    }
  ],
  "responses": {
    "200": {
      "description": "Success",
      "headers": {
        "X-Request-Id": {
          "$ref": "#/components/headers/X-Request-Id"
        },
        "X-Arcmira-Version": {
          "$ref": "#/components/headers/X-Arcmira-Version"
        },
        "RateLimit-Limit": {
          "$ref": "#/components/headers/RateLimit-Limit"
        },
        "RateLimit-Remaining": {
          "$ref": "#/components/headers/RateLimit-Remaining"
        },
        "RateLimit-Reset": {
          "$ref": "#/components/headers/RateLimit-Reset"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MentionListResponse"
          }
        }
      }
    },
    "400": {
      "$ref": "#/components/responses/InvalidRequest"
    },
    "401": {
      "$ref": "#/components/responses/AuthenticationError"
    },
    "402": {
      "$ref": "#/components/responses/QuotaExceeded"
    },
    "403": {
      "$ref": "#/components/responses/PermissionError"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/ServerError"
    }
  }
}