{ "openapi": "3.0.3", "info": { "title": "Influencity API", "version": "1.0.0", "description": "Influencity public REST API.\n\n## Authentication\n\nProtected endpoints require a valid Influencity API token.\nSend the token in the `Authorization` header using the Bearer scheme:\n\n```\nAuthorization: Bearer \n```\n\nRequests without a valid token receive `401 Unauthorized` with a JSON error body.\n\n## Rate limits\n\nRate limits apply per organization (brand). All API keys issued to the same organization share one limit pool—not per key.\n\nDocumented limits may change; Influencity will communicate material updates.\n\n**Default limit:** 10 requests/second (burst 10). **Daily quota:** 100000 requests per organization.\n\nSuccessful responses may include `X-RateLimit-Limit` and `X-RateLimit-Reset` so clients can pace requests.\n\n**Endpoint-specific limits:**\n- `POST /v1/trackings/{trackingId}/refresh`: 1 req/s (burst 1)\n- `POST /v1/profiles`: 2 req/s (burst 2)", "x-logo": { "url": "./assets/Logo.svg", "altText": "Influencity", "href": "#" } }, "servers": [ { "url": "https://api.influencity.com", "description": "Shared API domain (prod)" } ], "tags": [ { "name": "Content Tracking", "description": "Content Tracking service endpoints." }, { "name": "Profiles", "description": "Profiles service endpoints." } ], "paths": { "/content-tracking/v1/health": { "get": { "summary": "Check service health", "operationId": "content-tracking_getHealth", "responses": { "200": { "description": "Service is healthy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_HealthResponse" } } } } }, "tags": [ "Content Tracking" ] } }, "/content-tracking/v1/trackings": { "post": { "summary": "Create a custom tracking", "operationId": "content-tracking_createTracking", "description": "Creates a custom content tracking for the authenticated brand.", "security": [ { "BearerApiToken": [] } ], "x-influencity-rate-limit": { "steadyStateRps": 10, "burstRps": 10, "dailyQuota": 100000, "limitTier": "default" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_CreateTrackingRequest" } } } }, "responses": { "201": { "description": "Custom tracking created.", "headers": { "X-RateLimit-Limit": { "description": "Configured steady-state request rate (requests per second) for this endpoint.", "schema": { "type": "integer", "example": 10 } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) when the current rate-limit window resets.", "schema": { "type": "integer", "example": 1700000001 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_CreateTrackingResponse" } } } }, "400": { "description": "Invalid request payload or validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request" } } } } }, "401": { "description": "Missing or invalid API token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API token" } } } } }, "403": { "description": "The requested capability is not enabled for this brand plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "FEATURE_NOT_ENABLED", "message": "This feature is not enabled for your plan" } } } } }, "409": { "description": "A tracking with this name already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "CONTENT_TRACKING_NAME_DUPLICATED", "message": "A tracking with this name already exists" } } } } }, "422": { "description": "A business rule was violated (for example the brand profile limit was exceeded).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "CONTENT_TRACKING_PROFILES_LIMIT_EXCEEDED", "message": "Content tracking profile limit exceeded" } } } } }, "429": { "description": "Request rate exceeded (short-term throttle) or daily organization quota exhausted. `error.code` is `RATE_LIMIT_EXCEEDED` for throttling (may include `Retry-After`) or `QUOTA_EXCEEDED` when the daily quota is used up.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying. Present for short-term throttling; omitted when the daily quota is exceeded.", "schema": { "type": "integer", "example": 60 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "examples": { "rateLimitExceeded": { "value": { "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Too many requests" } } }, "quotaExceeded": { "value": { "error": { "code": "QUOTA_EXCEEDED", "message": "Daily quota exceeded" } } } } } } }, "502": { "description": "The API could not complete the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "BAD_GATEWAY", "message": "The API could not complete the request" } } } } }, "503": { "description": "Service temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable" } } } } }, "504": { "description": "The request timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "REQUEST_TIMEOUT", "message": "The request timed out" } } } } } }, "tags": [ "Content Tracking" ] }, "get": { "summary": "List trackings", "operationId": "content-tracking_listTrackings", "description": "Returns paginated content trackings for the authenticated brand. Example: `curl \"$BASE/v1/trackings?page=1&limit=20&sortBy=startDate&sortOrder=desc\" -H \"Authorization: Bearer $TOKEN\"`.", "security": [ { "BearerApiToken": [] } ], "x-influencity-rate-limit": { "steadyStateRps": 10, "burstRps": 10, "dailyQuota": 100000, "limitTier": "default" }, "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "default": 1, "description": "1-based page number.", "example": 1 }, "required": false, "description": "1-based page number (default 1).", "name": "page", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Page size (max 100).", "example": 20 }, "required": false, "description": "Page size (default 20, max 100).", "name": "limit", "in": "query" }, { "schema": { "type": "string", "enum": [ "name", "startDate", "endDate", "status", "type", "createdAt", "_id" ], "default": "startDate", "description": "Field to sort by.", "example": "startDate" }, "required": false, "description": "Sort field (default startDate).", "name": "sortBy", "in": "query" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort direction.", "example": "desc" }, "required": false, "description": "Sort direction (default desc).", "name": "sortOrder", "in": "query" } ], "responses": { "200": { "description": "Paginated trackings for the authenticated brand.", "headers": { "X-RateLimit-Limit": { "description": "Configured steady-state request rate (requests per second) for this endpoint.", "schema": { "type": "integer", "example": 10 } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) when the current rate-limit window resets.", "schema": { "type": "integer", "example": 1700000001 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ListTrackingsResponse" } } } }, "400": { "description": "Invalid request payload or validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request" } } } } }, "401": { "description": "Missing or invalid API token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API token" } } } } }, "403": { "description": "The requested capability is not enabled for this brand plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "FEATURE_NOT_ENABLED", "message": "This feature is not enabled for your plan" } } } } }, "429": { "description": "Request rate exceeded (short-term throttle) or daily organization quota exhausted. `error.code` is `RATE_LIMIT_EXCEEDED` for throttling (may include `Retry-After`) or `QUOTA_EXCEEDED` when the daily quota is used up.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying. Present for short-term throttling; omitted when the daily quota is exceeded.", "schema": { "type": "integer", "example": 60 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "examples": { "rateLimitExceeded": { "value": { "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Too many requests" } } }, "quotaExceeded": { "value": { "error": { "code": "QUOTA_EXCEEDED", "message": "Daily quota exceeded" } } } } } } }, "502": { "description": "The API could not complete the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "BAD_GATEWAY", "message": "The API could not complete the request" } } } } }, "503": { "description": "Service temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable" } } } } }, "504": { "description": "The request timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "REQUEST_TIMEOUT", "message": "The request timed out" } } } } } }, "tags": [ "Content Tracking" ] } }, "/content-tracking/v1/trackings/profile": { "post": { "summary": "Create a profile tracking", "operationId": "content-tracking_createProfileTracking", "description": "Creates a profile-type content tracking for one owned profile. Name and start date are generated by the API; `brandId` and `createdFrom` come from the API token.", "security": [ { "BearerApiToken": [] } ], "x-influencity-rate-limit": { "steadyStateRps": 10, "burstRps": 10, "dailyQuota": 100000, "limitTier": "default" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_CreateProfileTrackingRequest" } } } }, "responses": { "201": { "description": "Profile tracking created.", "headers": { "X-RateLimit-Limit": { "description": "Configured steady-state request rate (requests per second) for this endpoint.", "schema": { "type": "integer", "example": 10 } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) when the current rate-limit window resets.", "schema": { "type": "integer", "example": 1700000001 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_CreateProfileTrackingResponse" } } } }, "400": { "description": "Invalid request payload or validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request" } } } } }, "401": { "description": "Missing or invalid API token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API token" } } } } }, "403": { "description": "The requested capability is not enabled for this brand plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "FEATURE_NOT_ENABLED", "message": "This feature is not enabled for your plan" } } } } }, "404": { "description": "Profile was not found or does not belong to the authenticated brand.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" } } } } }, "409": { "description": "This profile already has a profile content tracking.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "CONTENT_TRACKING_PROFILE_DUPLICATED", "message": "This profile already has a profile content tracking" } } } } }, "422": { "description": "Brand content-tracking profile limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "CONTENT_TRACKING_PROFILES_LIMIT_EXCEEDED", "message": "Content tracking profile limit exceeded" } } } } }, "429": { "description": "Request rate exceeded (short-term throttle) or daily organization quota exhausted. `error.code` is `RATE_LIMIT_EXCEEDED` for throttling (may include `Retry-After`) or `QUOTA_EXCEEDED` when the daily quota is used up.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying. Present for short-term throttling; omitted when the daily quota is exceeded.", "schema": { "type": "integer", "example": 60 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "examples": { "rateLimitExceeded": { "value": { "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Too many requests" } } }, "quotaExceeded": { "value": { "error": { "code": "QUOTA_EXCEEDED", "message": "Daily quota exceeded" } } } } } } }, "502": { "description": "The API could not complete the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "BAD_GATEWAY", "message": "The API could not complete the request" } } } } }, "503": { "description": "Service temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable" } } } } }, "504": { "description": "The request timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "REQUEST_TIMEOUT", "message": "The request timed out" } } } } } }, "tags": [ "Content Tracking" ] } }, "/content-tracking/v1/trackings/{trackingId}/profiles": { "delete": { "summary": "Remove profiles from a tracking", "operationId": "content-tracking_removeTrackingProfiles", "description": "Removes profile ObjectIds from an existing content tracking for the authenticated brand. The operation is idempotent: profiles not linked to the tracking do not fail the request. Duplicate IDs in the request body are collapsed to a unique list. Profile-type trackings are rejected with 400.", "security": [ { "BearerApiToken": [] } ], "x-influencity-rate-limit": { "steadyStateRps": 10, "burstRps": 10, "dailyQuota": 100000, "limitTier": "default" }, "parameters": [ { "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "Tracking identifier.", "example": "507f1f77bcf86cd799439011" }, "required": true, "description": "Tracking identifier.", "name": "trackingId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_RemoveTrackingProfilesRequest" } } } }, "responses": { "200": { "description": "Profiles accepted for removal. `removedProfileIds` is the deduplicated request list, not a confirmation of newly unlinked profiles. Already-unlinked IDs may appear in the array.", "headers": { "X-RateLimit-Limit": { "description": "Configured steady-state request rate (requests per second) for this endpoint.", "schema": { "type": "integer", "example": 10 } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) when the current rate-limit window resets.", "schema": { "type": "integer", "example": 1700000001 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_RemoveTrackingProfilesResponse" } } } }, "400": { "description": "Invalid request payload or validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request" } } } } }, "401": { "description": "Missing or invalid API token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API token" } } } } }, "403": { "description": "The requested capability is not enabled for this brand plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "FEATURE_NOT_ENABLED", "message": "This feature is not enabled for your plan" } } } } }, "404": { "description": "Tracking or profile was not found, or does not belong to the authenticated brand.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" } } } } }, "429": { "description": "Request rate exceeded (short-term throttle) or daily organization quota exhausted. `error.code` is `RATE_LIMIT_EXCEEDED` for throttling (may include `Retry-After`) or `QUOTA_EXCEEDED` when the daily quota is used up.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying. Present for short-term throttling; omitted when the daily quota is exceeded.", "schema": { "type": "integer", "example": 60 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "examples": { "rateLimitExceeded": { "value": { "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Too many requests" } } }, "quotaExceeded": { "value": { "error": { "code": "QUOTA_EXCEEDED", "message": "Daily quota exceeded" } } } } } } }, "502": { "description": "The API could not complete the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "BAD_GATEWAY", "message": "The API could not complete the request" } } } } }, "503": { "description": "Service temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable" } } } } }, "504": { "description": "The request timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "REQUEST_TIMEOUT", "message": "The request timed out" } } } } } }, "tags": [ "Content Tracking" ] }, "post": { "summary": "Add profiles to a tracking", "operationId": "content-tracking_addTrackingProfiles", "description": "Attaches profile ObjectIds to an existing content tracking for the authenticated brand. The operation is idempotent: profiles already linked to the tracking do not fail the request. Duplicate IDs in the request body are collapsed to a unique list.", "security": [ { "BearerApiToken": [] } ], "x-influencity-rate-limit": { "steadyStateRps": 10, "burstRps": 10, "dailyQuota": 100000, "limitTier": "default" }, "parameters": [ { "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "Tracking identifier.", "example": "507f1f77bcf86cd799439011" }, "required": true, "description": "Tracking identifier.", "name": "trackingId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_AddTrackingProfilesRequest" } } } }, "responses": { "200": { "description": "Profiles accepted. `addedProfileIds` is the deduplicated request list, not a confirmation of newly persisted links. Already-linked IDs may appear in the array.", "headers": { "X-RateLimit-Limit": { "description": "Configured steady-state request rate (requests per second) for this endpoint.", "schema": { "type": "integer", "example": 10 } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) when the current rate-limit window resets.", "schema": { "type": "integer", "example": 1700000001 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_AddTrackingProfilesResponse" } } } }, "400": { "description": "Invalid request payload or validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request" } } } } }, "401": { "description": "Missing or invalid API token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API token" } } } } }, "403": { "description": "The requested capability is not enabled for this brand plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "FEATURE_NOT_ENABLED", "message": "This feature is not enabled for your plan" } } } } }, "404": { "description": "Tracking or profile was not found, or does not belong to the authenticated brand.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" } } } } }, "409": { "description": "Tracking is finished and cannot accept new profiles.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "CONTENT_TRACKING_INACTIVE", "message": "Tracking is finished and cannot accept new profiles" } } } } }, "422": { "description": "Brand content-tracking profile limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "CONTENT_TRACKING_PROFILES_LIMIT_EXCEEDED", "message": "Content tracking profile limit exceeded" } } } } }, "429": { "description": "Request rate exceeded (short-term throttle) or daily organization quota exhausted. `error.code` is `RATE_LIMIT_EXCEEDED` for throttling (may include `Retry-After`) or `QUOTA_EXCEEDED` when the daily quota is used up.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying. Present for short-term throttling; omitted when the daily quota is exceeded.", "schema": { "type": "integer", "example": 60 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "examples": { "rateLimitExceeded": { "value": { "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Too many requests" } } }, "quotaExceeded": { "value": { "error": { "code": "QUOTA_EXCEEDED", "message": "Daily quota exceeded" } } } } } } }, "502": { "description": "The API could not complete the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "BAD_GATEWAY", "message": "The API could not complete the request" } } } } }, "503": { "description": "Service temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable" } } } } }, "504": { "description": "The request timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "REQUEST_TIMEOUT", "message": "The request timed out" } } } } } }, "tags": [ "Content Tracking" ] } }, "/content-tracking/v1/trackings/pause": { "post": { "summary": "Pause trackings", "operationId": "content-tracking_pauseTrackings", "description": "Pauses one or more active content trackings for the authenticated brand. Duplicate IDs in the request body are collapsed to a unique list. All listed trackings must exist, belong to the brand, and be ACTIVE; otherwise the request fails.", "security": [ { "BearerApiToken": [] } ], "x-influencity-rate-limit": { "steadyStateRps": 10, "burstRps": 10, "dailyQuota": 100000, "limitTier": "default" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_PauseTrackingsRequest" } } } }, "responses": { "200": { "description": "Trackings accepted for pause. `pausedTrackingIds` is the deduplicated request list.", "headers": { "X-RateLimit-Limit": { "description": "Configured steady-state request rate (requests per second) for this endpoint.", "schema": { "type": "integer", "example": 10 } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) when the current rate-limit window resets.", "schema": { "type": "integer", "example": 1700000001 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_PauseTrackingsResponse" } } } }, "400": { "description": "Invalid request payload or validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request" } } } } }, "401": { "description": "Missing or invalid API token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API token" } } } } }, "403": { "description": "The requested capability is not enabled for this brand plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "FEATURE_NOT_ENABLED", "message": "This feature is not enabled for your plan" } } } } }, "404": { "description": "One or more trackings were not found, or do not belong to the authenticated brand.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" } } } } }, "422": { "description": "One or more trackings are not active and cannot be paused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "CONTENT_TRACKING_NOT_ACTIVE", "message": "One or more trackings are not active and cannot be paused" } } } } }, "429": { "description": "Request rate exceeded (short-term throttle) or daily organization quota exhausted. `error.code` is `RATE_LIMIT_EXCEEDED` for throttling (may include `Retry-After`) or `QUOTA_EXCEEDED` when the daily quota is used up.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying. Present for short-term throttling; omitted when the daily quota is exceeded.", "schema": { "type": "integer", "example": 60 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "examples": { "rateLimitExceeded": { "value": { "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Too many requests" } } }, "quotaExceeded": { "value": { "error": { "code": "QUOTA_EXCEEDED", "message": "Daily quota exceeded" } } } } } } }, "502": { "description": "The API could not complete the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "BAD_GATEWAY", "message": "The API could not complete the request" } } } } }, "503": { "description": "Service temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable" } } } } }, "504": { "description": "The request timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "REQUEST_TIMEOUT", "message": "The request timed out" } } } } } }, "tags": [ "Content Tracking" ] } }, "/content-tracking/v1/trackings/resume": { "post": { "summary": "Resume trackings", "operationId": "content-tracking_resumeTrackings", "description": "Resumes one or more paused content trackings for the authenticated brand. Duplicate IDs in the request body are collapsed to a unique list. All listed trackings must exist, belong to the brand, and be PAUSED; otherwise the request fails. Resuming may also fail when the brand profile quota would be exceeded.", "security": [ { "BearerApiToken": [] } ], "x-influencity-rate-limit": { "steadyStateRps": 10, "burstRps": 10, "dailyQuota": 100000, "limitTier": "default" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ResumeTrackingsRequest" } } } }, "responses": { "200": { "description": "Trackings accepted for resume. `resumedTrackingIds` is the deduplicated request list.", "headers": { "X-RateLimit-Limit": { "description": "Configured steady-state request rate (requests per second) for this endpoint.", "schema": { "type": "integer", "example": 10 } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) when the current rate-limit window resets.", "schema": { "type": "integer", "example": 1700000001 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ResumeTrackingsResponse" } } } }, "400": { "description": "Invalid request payload or validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request" } } } } }, "401": { "description": "Missing or invalid API token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API token" } } } } }, "403": { "description": "The requested capability is not enabled for this brand plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "FEATURE_NOT_ENABLED", "message": "This feature is not enabled for your plan" } } } } }, "404": { "description": "One or more trackings were not found, or do not belong to the authenticated brand.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" } } } } }, "422": { "description": "Business rule violation. Common `error.code` values include `CONTENT_TRACKING_NOT_PAUSED` and `CONTENT_TRACKING_PROFILES_LIMIT_EXCEEDED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "examples": { "notPaused": { "value": { "error": { "code": "CONTENT_TRACKING_NOT_PAUSED", "message": "One or more trackings are not paused and cannot be resumed" } } }, "profilesLimitExceeded": { "value": { "error": { "code": "CONTENT_TRACKING_PROFILES_LIMIT_EXCEEDED", "message": "Content tracking profile limit exceeded" } } } } } } }, "429": { "description": "Request rate exceeded (short-term throttle) or daily organization quota exhausted. `error.code` is `RATE_LIMIT_EXCEEDED` for throttling (may include `Retry-After`) or `QUOTA_EXCEEDED` when the daily quota is used up.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying. Present for short-term throttling; omitted when the daily quota is exceeded.", "schema": { "type": "integer", "example": 60 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "examples": { "rateLimitExceeded": { "value": { "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Too many requests" } } }, "quotaExceeded": { "value": { "error": { "code": "QUOTA_EXCEEDED", "message": "Daily quota exceeded" } } } } } } }, "502": { "description": "The API could not complete the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "BAD_GATEWAY", "message": "The API could not complete the request" } } } } }, "503": { "description": "Service temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable" } } } } }, "504": { "description": "The request timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "REQUEST_TIMEOUT", "message": "The request timed out" } } } } } }, "tags": [ "Content Tracking" ] } }, "/content-tracking/v1/trackings/{trackingId}/publications": { "get": { "summary": "List publications in a tracking", "operationId": "content-tracking_getTrackingPublications", "description": "Returns paginated publications collected in a content tracking (metrics, music, stickers, and related fields). Content filters are not supported in this version.", "security": [ { "BearerApiToken": [] } ], "x-influencity-rate-limit": { "steadyStateRps": 10, "burstRps": 10, "dailyQuota": 100000, "limitTier": "default" }, "parameters": [ { "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "Tracking identifier.", "example": "507f1f77bcf86cd799439011" }, "required": true, "description": "Tracking identifier.", "name": "trackingId", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "default": 1, "description": "1-based page number.", "example": 1 }, "required": false, "description": "1-based page number (default 1).", "name": "page", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Page size (max 100).", "example": 20 }, "required": false, "description": "Page size (default 20, max 100).", "name": "limit", "in": "query" }, { "schema": { "type": "string", "enum": [ "publicationDate", "likes", "views", "comments", "shares", "saves", "engagement", "impressions", "profile", "_id" ], "description": "Sort field allow-list. When omitted, influ-api sends publicationDate.", "example": "publicationDate" }, "required": false, "description": "Sort field (closed enum).", "name": "sortBy", "in": "query" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort direction.", "example": "desc" }, "required": false, "description": "Sort direction (default desc).", "name": "sortOrder", "in": "query" } ], "responses": { "200": { "description": "Paginated publications for the tracking.", "headers": { "X-RateLimit-Limit": { "description": "Configured steady-state request rate (requests per second) for this endpoint.", "schema": { "type": "integer", "example": 10 } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) when the current rate-limit window resets.", "schema": { "type": "integer", "example": 1700000001 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_GetTrackingPublicationsResponse" } } } }, "400": { "description": "Invalid request payload or validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request" } } } } }, "401": { "description": "Missing or invalid API token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API token" } } } } }, "403": { "description": "The requested capability is not enabled for this brand plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "FEATURE_NOT_ENABLED", "message": "This feature is not enabled for your plan" } } } } }, "404": { "description": "Tracking was not found or does not belong to the authenticated brand.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" } } } } }, "429": { "description": "Request rate exceeded (short-term throttle) or daily organization quota exhausted. `error.code` is `RATE_LIMIT_EXCEEDED` for throttling (may include `Retry-After`) or `QUOTA_EXCEEDED` when the daily quota is used up.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying. Present for short-term throttling; omitted when the daily quota is exceeded.", "schema": { "type": "integer", "example": 60 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "examples": { "rateLimitExceeded": { "value": { "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Too many requests" } } }, "quotaExceeded": { "value": { "error": { "code": "QUOTA_EXCEEDED", "message": "Daily quota exceeded" } } } } } } }, "502": { "description": "The API could not complete the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "BAD_GATEWAY", "message": "The API could not complete the request" } } } } }, "503": { "description": "Service temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable" } } } } }, "504": { "description": "The request timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "REQUEST_TIMEOUT", "message": "The request timed out" } } } } } }, "tags": [ "Content Tracking" ] } }, "/content-tracking/v1/trackings/quota": { "get": { "summary": "Get content tracking profile quota", "operationId": "content-tracking_getTrackingQuota", "description": "Returns how many profile slots the authenticated brand can still link to active content trackings. This quota applies when registering profiles on trackings, not when running IRM profile analysis. Both `remainingProfilesInTracking` and `profilesLimit` are null when unlimited.", "security": [ { "BearerApiToken": [] } ], "x-influencity-rate-limit": { "steadyStateRps": 10, "burstRps": 10, "dailyQuota": 100000, "limitTier": "default" }, "responses": { "200": { "description": "Content tracking profile-slot quota for the authenticated brand (not IRM analysis quota).", "headers": { "X-RateLimit-Limit": { "description": "Configured steady-state request rate (requests per second) for this endpoint.", "schema": { "type": "integer", "example": 10 } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) when the current rate-limit window resets.", "schema": { "type": "integer", "example": 1700000001 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_GetTrackingQuotaResponse" } } } }, "400": { "description": "Invalid request payload or validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request" } } } } }, "401": { "description": "Missing or invalid API token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API token" } } } } }, "403": { "description": "The requested capability is not enabled for this brand plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "FEATURE_NOT_ENABLED", "message": "This feature is not enabled for your plan" } } } } }, "429": { "description": "Request rate exceeded (short-term throttle) or daily organization quota exhausted. `error.code` is `RATE_LIMIT_EXCEEDED` for throttling (may include `Retry-After`) or `QUOTA_EXCEEDED` when the daily quota is used up.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying. Present for short-term throttling; omitted when the daily quota is exceeded.", "schema": { "type": "integer", "example": 60 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "examples": { "rateLimitExceeded": { "value": { "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Too many requests" } } }, "quotaExceeded": { "value": { "error": { "code": "QUOTA_EXCEEDED", "message": "Daily quota exceeded" } } } } } } }, "502": { "description": "The API could not complete the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "BAD_GATEWAY", "message": "The API could not complete the request" } } } } }, "503": { "description": "Service temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable" } } } } }, "504": { "description": "The request timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "REQUEST_TIMEOUT", "message": "The request timed out" } } } } } }, "tags": [ "Content Tracking" ] } }, "/content-tracking/v1/trackings/{trackingId}/refresh": { "post": { "summary": "Refresh a tracking", "operationId": "content-tracking_refreshTracking", "security": [ { "BearerApiToken": [] } ], "x-influencity-rate-limit": { "steadyStateRps": 1, "burstRps": 1, "dailyQuota": 100000, "limitTier": "endpoint" }, "description": "Requests a data refresh for an existing content tracking belonging to the authenticated brand. No request body. Refresh may be rejected when the feature is disabled, the tracking has no profiles, or the brand cooldown has not elapsed (domain 429 with `Retry-After`). **Rate limit for this endpoint:** 1 request/second (burst 1). Daily quota and shared limits are described under **Rate limits** above.", "parameters": [ { "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "Tracking identifier.", "example": "507f1f77bcf86cd799439011" }, "required": true, "description": "Tracking identifier.", "name": "trackingId", "in": "path" } ], "responses": { "200": { "description": "Refresh accepted and queued for processing.", "headers": { "X-RateLimit-Limit": { "description": "Configured steady-state request rate (requests per second) for this endpoint.", "schema": { "type": "integer", "example": 1 } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) when the current rate-limit window resets.", "schema": { "type": "integer", "example": 1700000001 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_RefreshTrackingResponse" } } } }, "400": { "description": "Invalid request payload or validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request" } } } } }, "401": { "description": "Missing or invalid API token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API token" } } } } }, "403": { "description": "The requested capability is not enabled for this brand plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "FEATURE_NOT_ENABLED", "message": "This feature is not enabled for your plan" } } } } }, "404": { "description": "Tracking was not found, or does not belong to the authenticated brand.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" } } } } }, "422": { "description": "Business rule violation. Common `error.code` values include `CONTENT_TRACKING_REFRESH_NOT_ENABLED` and `CONTENT_TRACKING_REFRESH_NO_PROFILES`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "examples": { "refreshNotEnabled": { "value": { "error": { "code": "CONTENT_TRACKING_REFRESH_NOT_ENABLED", "message": "Content tracking refresh is not enabled" } } }, "refreshNoProfiles": { "value": { "error": { "code": "CONTENT_TRACKING_REFRESH_NO_PROFILES", "message": "No profiles available to refresh" } } } } } } }, "429": { "description": "Domain cooldown (`CONTENT_TRACKING_REFRESH_TOO_SOON`) or API Gateway throttle / quota. Domain too-soon includes `Retry-After` (seconds) and `error.details` with `retryAfterSeconds` and `hoursRemaining`. Throttle uses `RATE_LIMIT_EXCEEDED`; daily quota uses `QUOTA_EXCEEDED`.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying. Present for domain cooldown and short-term throttling; omitted when the daily quota is exceeded or cooldown metadata is unavailable.", "schema": { "type": "integer", "example": 9000 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "examples": { "refreshTooSoon": { "value": { "error": { "code": "CONTENT_TRACKING_REFRESH_TOO_SOON", "message": "Content tracking refresh was requested too soon", "details": { "retryAfterSeconds": 9000, "hoursRemaining": 2.5 } } } }, "rateLimitExceeded": { "value": { "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Too many requests" } } }, "quotaExceeded": { "value": { "error": { "code": "QUOTA_EXCEEDED", "message": "Daily quota exceeded" } } } } } } }, "502": { "description": "The API could not complete the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "BAD_GATEWAY", "message": "The API could not complete the request" } } } } }, "503": { "description": "Service temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable" } } } } }, "504": { "description": "The request timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/content-tracking_ApiErrorResponse" }, "example": { "error": { "code": "REQUEST_TIMEOUT", "message": "The request timed out" } } } } } }, "tags": [ "Content Tracking" ] } }, "/profiles/v1/health": { "get": { "summary": "Check service health", "operationId": "profiles_getHealth", "responses": { "200": { "description": "Service is healthy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_HealthResponse" } } } } }, "tags": [ "Profiles" ] } }, "/profiles/v1/profiles": { "post": { "summary": "Add a profile", "operationId": "profiles_addProfile", "security": [ { "BearerApiToken": [] } ], "x-influencity-rate-limit": { "steadyStateRps": 2, "burstRps": 2, "dailyQuota": 100000, "limitTier": "endpoint" }, "description": "**Rate limit for this endpoint:** 2 requests/second (burst 2). Daily quota and shared limits are described under **Rate limits** above.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_AddProfileRequest" } } } }, "responses": { "201": { "description": "Profile created.", "headers": { "X-RateLimit-Limit": { "description": "Configured steady-state request rate (requests per second) for this endpoint.", "schema": { "type": "integer", "example": 2 } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) when the current rate-limit window resets.", "schema": { "type": "integer", "example": 1700000001 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_AddProfileResponse" } } } }, "400": { "description": "Invalid request payload or validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request" } } } } }, "401": { "description": "Missing or invalid API token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API token" } } } } }, "403": { "description": "The requested capability is not enabled for this brand plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "FEATURE_NOT_ENABLED", "message": "This feature is not enabled for your plan" } } } } }, "404": { "description": "The social profile could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "IRM_PROFILE_NOT_EXISTS", "message": "Profile does not exist" } } } } }, "409": { "description": "A profile with the same network and username already exists for this brand. When available, `error.details.profileId` is the existing profile identifier so clients can retrieve it instead of creating a duplicate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_AddProfileConflictError" }, "example": { "error": { "code": "IRM_PROFILE_DUPLICATED", "message": "Profile already exists", "details": { "profileId": "507f1f77bcf86cd799439011" } } } } } }, "422": { "description": "The brand has no remaining profile analyses for the current period.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "PROFILE_ANALYSIS_LIMIT_EXCEEDED", "message": "Profile analysis limit exceeded" } } } } }, "429": { "description": "Request rate exceeded (short-term throttle) or daily organization quota exhausted. `error.code` is `RATE_LIMIT_EXCEEDED` for throttling (may include `Retry-After`) or `QUOTA_EXCEEDED` when the daily quota is used up.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying. Present for short-term throttling; omitted when the daily quota is exceeded.", "schema": { "type": "integer", "example": 60 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "examples": { "rateLimitExceeded": { "value": { "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Too many requests" } } }, "quotaExceeded": { "value": { "error": { "code": "QUOTA_EXCEEDED", "message": "Daily quota exceeded" } } } } } } }, "502": { "description": "The API could not complete the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "BAD_GATEWAY", "message": "The API could not complete the request" } } } } }, "503": { "description": "Service temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable" } } } } }, "504": { "description": "The request timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "REQUEST_TIMEOUT", "message": "The request timed out" } } } } } }, "tags": [ "Profiles" ] }, "get": { "summary": "Get a profile by social network and username", "operationId": "profiles_getProfileByLookup", "security": [ { "BearerApiToken": [] } ], "x-influencity-rate-limit": { "steadyStateRps": 10, "burstRps": 10, "dailyQuota": 100000, "limitTier": "default" }, "parameters": [ { "schema": { "type": "string", "enum": [ "instagram", "youtube", "tiktok", "twitter", "facebook", "snapchat", "tumblr", "twitch", "vk", "weibo", "pinterest", "douyin" ], "description": "Social network of the profile to look up. Any IRM network is accepted.", "example": "instagram" }, "required": true, "description": "Social network of the profile to look up.", "name": "socialNetwork", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "description": "Stored profile username for the given social network.", "example": "influencity" }, "required": true, "description": "Stored profile username for the given social network.", "name": "username", "in": "query" } ], "responses": { "200": { "description": "Profile retrieved.", "headers": { "X-RateLimit-Limit": { "description": "Configured steady-state request rate (requests per second) for this endpoint.", "schema": { "type": "integer", "example": 10 } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) when the current rate-limit window resets.", "schema": { "type": "integer", "example": 1700000001 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_GetProfileResponse" } } } }, "400": { "description": "Invalid request payload or validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request" } } } } }, "401": { "description": "Missing or invalid API token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API token" } } } } }, "403": { "description": "IRM profiles are not enabled for this brand.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "FORBIDDEN", "message": "You do not have permission to perform this action" } } } } }, "404": { "description": "The profile does not exist or does not belong to the authenticated brand.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "IRM_PROFILE_NOT_EXISTS", "message": "Profile does not exist" } } } } }, "429": { "description": "Request rate exceeded (short-term throttle) or daily organization quota exhausted. `error.code` is `RATE_LIMIT_EXCEEDED` for throttling (may include `Retry-After`) or `QUOTA_EXCEEDED` when the daily quota is used up.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying. Present for short-term throttling; omitted when the daily quota is exceeded.", "schema": { "type": "integer", "example": 60 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "examples": { "rateLimitExceeded": { "value": { "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Too many requests" } } }, "quotaExceeded": { "value": { "error": { "code": "QUOTA_EXCEEDED", "message": "Daily quota exceeded" } } } } } } }, "502": { "description": "The API could not complete the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "BAD_GATEWAY", "message": "The API could not complete the request" } } } } }, "503": { "description": "Service temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable" } } } } }, "504": { "description": "The request timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "REQUEST_TIMEOUT", "message": "The request timed out" } } } } } }, "tags": [ "Profiles" ] } }, "/profiles/v1/profiles/{profileId}": { "get": { "summary": "Get a profile by ID", "operationId": "profiles_getProfile", "security": [ { "BearerApiToken": [] } ], "x-influencity-rate-limit": { "steadyStateRps": 10, "burstRps": 10, "dailyQuota": 100000, "limitTier": "default" }, "parameters": [ { "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "Profile identifier.", "example": "507f1f77bcf86cd799439011" }, "required": true, "description": "Profile identifier.", "name": "profileId", "in": "path" } ], "responses": { "200": { "description": "Profile retrieved.", "headers": { "X-RateLimit-Limit": { "description": "Configured steady-state request rate (requests per second) for this endpoint.", "schema": { "type": "integer", "example": 10 } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) when the current rate-limit window resets.", "schema": { "type": "integer", "example": 1700000001 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_GetProfileResponse" } } } }, "400": { "description": "Invalid request payload or validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request" } } } } }, "401": { "description": "Missing or invalid API token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API token" } } } } }, "403": { "description": "IRM profiles are not enabled for this brand.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "FORBIDDEN", "message": "You do not have permission to perform this action" } } } } }, "404": { "description": "The profile does not exist or does not belong to the authenticated brand.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "IRM_PROFILE_NOT_EXISTS", "message": "Profile does not exist" } } } } }, "429": { "description": "Request rate exceeded (short-term throttle) or daily organization quota exhausted. `error.code` is `RATE_LIMIT_EXCEEDED` for throttling (may include `Retry-After`) or `QUOTA_EXCEEDED` when the daily quota is used up.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying. Present for short-term throttling; omitted when the daily quota is exceeded.", "schema": { "type": "integer", "example": 60 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "examples": { "rateLimitExceeded": { "value": { "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Too many requests" } } }, "quotaExceeded": { "value": { "error": { "code": "QUOTA_EXCEEDED", "message": "Daily quota exceeded" } } } } } } }, "502": { "description": "The API could not complete the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "BAD_GATEWAY", "message": "The API could not complete the request" } } } } }, "503": { "description": "Service temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable" } } } } }, "504": { "description": "The request timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "REQUEST_TIMEOUT", "message": "The request timed out" } } } } } }, "tags": [ "Profiles" ] }, "delete": { "summary": "Delete a profile by ID", "operationId": "profiles_deleteProfile", "security": [ { "BearerApiToken": [] } ], "x-influencity-rate-limit": { "steadyStateRps": 10, "burstRps": 10, "dailyQuota": 100000, "limitTier": "default" }, "parameters": [ { "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "Profile identifier.", "example": "507f1f77bcf86cd799439011" }, "required": true, "description": "Profile identifier.", "name": "profileId", "in": "path" } ], "responses": { "200": { "description": "Profile deleted.", "headers": { "X-RateLimit-Limit": { "description": "Configured steady-state request rate (requests per second) for this endpoint.", "schema": { "type": "integer", "example": 10 } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) when the current rate-limit window resets.", "schema": { "type": "integer", "example": 1700000001 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_DeleteProfileResponse" } } } }, "400": { "description": "Invalid request payload or validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request" } } } } }, "401": { "description": "Missing or invalid API token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API token" } } } } }, "403": { "description": "IRM profiles are not enabled for this brand.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "FORBIDDEN", "message": "You do not have permission to perform this action" } } } } }, "404": { "description": "The profile does not exist or does not belong to the authenticated brand.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "IRM_PROFILE_NOT_EXISTS", "message": "Profile does not exist" } } } } }, "409": { "description": "The profile cannot be deleted because it has blocking relations (for example active trackings or campaigns).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "IRM_PROFILE_BLOCKING_RELATION", "message": "Profile cannot be deleted because it has blocking relations" } } } } }, "429": { "description": "Request rate exceeded (short-term throttle) or daily organization quota exhausted. `error.code` is `RATE_LIMIT_EXCEEDED` for throttling (may include `Retry-After`) or `QUOTA_EXCEEDED` when the daily quota is used up.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying. Present for short-term throttling; omitted when the daily quota is exceeded.", "schema": { "type": "integer", "example": 60 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "examples": { "rateLimitExceeded": { "value": { "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Too many requests" } } }, "quotaExceeded": { "value": { "error": { "code": "QUOTA_EXCEEDED", "message": "Daily quota exceeded" } } } } } } }, "502": { "description": "The API could not complete the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "BAD_GATEWAY", "message": "The API could not complete the request" } } } } }, "503": { "description": "Service temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable" } } } } }, "504": { "description": "The request timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "REQUEST_TIMEOUT", "message": "The request timed out" } } } } } }, "tags": [ "Profiles" ] } }, "/profiles/v1/profiles/quota": { "get": { "summary": "Get IRM profile analysis quota", "operationId": "profiles_getProfilesQuota", "description": "Returns how many profile analyses the authenticated brand can still run in the current period (analyze or refresh). This quota does not limit adding profiles without analysis. Both `remainingAnalysisPerPeriod` and `analysisLimitPerPeriod` are null when unlimited.", "security": [ { "BearerApiToken": [] } ], "x-influencity-rate-limit": { "steadyStateRps": 10, "burstRps": 10, "dailyQuota": 100000, "limitTier": "default" }, "responses": { "200": { "description": "Profile analysis quota for the authenticated brand (analyze/refresh operations, not profile additions).", "headers": { "X-RateLimit-Limit": { "description": "Configured steady-state request rate (requests per second) for this endpoint.", "schema": { "type": "integer", "example": 10 } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) when the current rate-limit window resets.", "schema": { "type": "integer", "example": 1700000001 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_GetProfilesQuotaResponse" } } } }, "400": { "description": "Invalid request payload or validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request" } } } } }, "401": { "description": "Missing or invalid API token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API token" } } } } }, "403": { "description": "The requested capability is not enabled for this brand plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "FEATURE_NOT_ENABLED", "message": "This feature is not enabled for your plan" } } } } }, "429": { "description": "Request rate exceeded (short-term throttle) or daily organization quota exhausted. `error.code` is `RATE_LIMIT_EXCEEDED` for throttling (may include `Retry-After`) or `QUOTA_EXCEEDED` when the daily quota is used up.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying. Present for short-term throttling; omitted when the daily quota is exceeded.", "schema": { "type": "integer", "example": 60 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "examples": { "rateLimitExceeded": { "value": { "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Too many requests" } } }, "quotaExceeded": { "value": { "error": { "code": "QUOTA_EXCEEDED", "message": "Daily quota exceeded" } } } } } } }, "502": { "description": "The API could not complete the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "BAD_GATEWAY", "message": "The API could not complete the request" } } } } }, "503": { "description": "Service temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable" } } } } }, "504": { "description": "The request timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "REQUEST_TIMEOUT", "message": "The request timed out" } } } } } }, "tags": [ "Profiles" ] } }, "/profiles/v1/profiles/{profileId}/analyze": { "post": { "summary": "Start profile analysis by ID", "operationId": "profiles_analyzeProfile", "security": [ { "BearerApiToken": [] } ], "x-influencity-rate-limit": { "steadyStateRps": 10, "burstRps": 10, "dailyQuota": 100000, "limitTier": "default" }, "parameters": [ { "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "Profile identifier.", "example": "507f1f77bcf86cd799439011" }, "required": true, "description": "Profile identifier.", "name": "profileId", "in": "path" } ], "responses": { "200": { "description": "Profile analysis queued, or existing analyzed profile returned when analysis data is already available.", "headers": { "X-RateLimit-Limit": { "description": "Configured steady-state request rate (requests per second) for this endpoint.", "schema": { "type": "integer", "example": 10 } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) when the current rate-limit window resets.", "schema": { "type": "integer", "example": 1700000001 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_AnalyzeProfileResponse" } } } }, "400": { "description": "Invalid request payload or validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request" } } } } }, "401": { "description": "Missing or invalid API token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API token" } } } } }, "403": { "description": "IRM profiles are not enabled for this brand.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "FORBIDDEN", "message": "You do not have permission to perform this action" } } } } }, "404": { "description": "The profile does not exist or does not belong to the authenticated brand.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "IRM_PROFILE_NOT_EXISTS", "message": "Profile does not exist" } } } } }, "409": { "description": "The profile is already being analyzed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "PROFILE_ANALYSIS_IN_PROGRESS", "message": "Profile analysis is already in progress" } } } } }, "422": { "description": "The brand has no remaining profile analyses for the current period.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "PROFILE_ANALYSIS_LIMIT_EXCEEDED", "message": "Profile analysis limit exceeded" } } } } }, "429": { "description": "Request rate exceeded (short-term throttle) or daily organization quota exhausted. `error.code` is `RATE_LIMIT_EXCEEDED` for throttling (may include `Retry-After`) or `QUOTA_EXCEEDED` when the daily quota is used up.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying. Present for short-term throttling; omitted when the daily quota is exceeded.", "schema": { "type": "integer", "example": 60 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "examples": { "rateLimitExceeded": { "value": { "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Too many requests" } } }, "quotaExceeded": { "value": { "error": { "code": "QUOTA_EXCEEDED", "message": "Daily quota exceeded" } } } } } } }, "502": { "description": "The API could not complete the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "BAD_GATEWAY", "message": "The API could not complete the request" } } } } }, "503": { "description": "Service temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable" } } } } }, "504": { "description": "The request timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "REQUEST_TIMEOUT", "message": "The request timed out" } } } } } }, "tags": [ "Profiles" ] } }, "/profiles/v1/profiles/{profileId}/refresh": { "post": { "summary": "Refresh an analyzed profile by ID", "operationId": "profiles_refreshProfile", "security": [ { "BearerApiToken": [] } ], "x-influencity-rate-limit": { "steadyStateRps": 10, "burstRps": 10, "dailyQuota": 100000, "limitTier": "default" }, "parameters": [ { "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "Profile identifier.", "example": "507f1f77bcf86cd799439011" }, "required": true, "description": "Profile identifier.", "name": "profileId", "in": "path" } ], "responses": { "200": { "description": "Profile refresh queued for an already analyzed profile.", "headers": { "X-RateLimit-Limit": { "description": "Configured steady-state request rate (requests per second) for this endpoint.", "schema": { "type": "integer", "example": 10 } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) when the current rate-limit window resets.", "schema": { "type": "integer", "example": 1700000001 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_RefreshProfileResponse" } } } }, "400": { "description": "Invalid request payload or validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request" } } } } }, "401": { "description": "Missing or invalid API token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API token" } } } } }, "403": { "description": "IRM profiles are not enabled for this brand.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "FORBIDDEN", "message": "You do not have permission to perform this action" } } } } }, "404": { "description": "The profile does not exist or does not belong to the authenticated brand.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "IRM_PROFILE_NOT_EXISTS", "message": "Profile does not exist" } } } } }, "409": { "description": "The profile is already being analyzed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "PROFILE_ANALYSIS_IN_PROGRESS", "message": "Profile analysis is already in progress" } } } } }, "422": { "description": "Business rule violation when refresh cannot proceed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "examples": { "profileNotAnalyzed": { "value": { "error": { "code": "PROFILE_NOT_ANALYZED", "message": "Profile has not been analyzed yet" } } }, "analysisLimitExceeded": { "value": { "error": { "code": "PROFILE_ANALYSIS_LIMIT_EXCEEDED", "message": "Profile analysis limit exceeded" } } } } } } }, "429": { "description": "Request rate exceeded (short-term throttle) or daily organization quota exhausted. `error.code` is `RATE_LIMIT_EXCEEDED` for throttling (may include `Retry-After`) or `QUOTA_EXCEEDED` when the daily quota is used up.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying. Present for short-term throttling; omitted when the daily quota is exceeded.", "schema": { "type": "integer", "example": 60 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "examples": { "rateLimitExceeded": { "value": { "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Too many requests" } } }, "quotaExceeded": { "value": { "error": { "code": "QUOTA_EXCEEDED", "message": "Daily quota exceeded" } } } } } } }, "502": { "description": "The API could not complete the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "BAD_GATEWAY", "message": "The API could not complete the request" } } } } }, "503": { "description": "Service temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable" } } } } }, "504": { "description": "The request timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profiles_ApiErrorResponse" }, "example": { "error": { "code": "REQUEST_TIMEOUT", "message": "The request timed out" } } } } } }, "tags": [ "Profiles" ] } } }, "components": { "schemas": { "ApiError": { "type": "object", "description": "Machine-readable error code and human-readable message.", "properties": { "code": { "type": "string", "description": "Stable error identifier for programmatic handling." }, "message": { "type": "string", "description": "Short explanation of the failure." }, "details": { "type": "object", "description": "Optional structured context (for example validation field errors).", "additionalProperties": true } }, "required": [ "code", "message" ] }, "ApiErrorResponse": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] }, "content-tracking_HealthResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ], "description": "Service health status.", "example": "ok" }, "service": { "type": "string", "description": "Service name.", "example": "content-tracking" }, "stage": { "type": "string", "description": "Deployment stage.", "example": "dev" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO timestamp generated by the service.", "example": "2026-07-22T12:00:00.000Z" } }, "required": [ "status", "service", "stage", "timestamp" ] }, "content-tracking_CreateTrackingResponse": { "type": "object", "properties": { "trackingId": { "type": "string", "description": "Created tracking identifier.", "example": "507f1f77bcf86cd799439011" }, "name": { "type": "string", "description": "Tracking display name.", "example": "My Campaign Tracking" }, "status": { "type": "string", "description": "Tracking status.", "example": "active" }, "startDate": { "type": "string", "description": "Normalized start date. Today UTC is returned as the instant the tracking started.", "example": "2027-01-15T00:00:00.000Z" }, "endDate": { "type": "string", "description": "Normalized end date.", "example": "2027-06-30T23:59:59.999Z" }, "createdFrom": { "type": "string", "description": "Origin of the tracking. Public API creates always report `api`.", "example": "api" } }, "required": [ "trackingId", "name", "status", "startDate", "endDate", "createdFrom" ] }, "content-tracking_CreateTrackingRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Tracking display name (unique per brand).", "example": "My Campaign Tracking" }, "description": { "type": "string", "description": "Optional tracking description. Not returned in the public 201 body.", "example": "Q3 brand mentions" }, "hashtags": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 5, "description": "Hashtag filters (max 5). Omit or pass [].", "example": [ "#brand" ] }, "mentions": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 5, "description": "Mention filters (max 5). Omit or pass [].", "example": [ "@handle" ] }, "keywords": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 5, "description": "Keyword filters (max 5). Omit or pass [].", "example": [ "keyword" ] }, "profileIds": { "type": "array", "items": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "description": "Optional profile ObjectIds to attach. Alone is not enough; content filters are required.", "example": [ "507f1f77bcf86cd799439011" ] }, "startDate": { "type": "string", "description": "Tracking start date (YYYY-MM-DD). Required. Must not be in the past (UTC). If it is today UTC, the tracking starts immediately.", "example": "2027-01-15" }, "endDate": { "type": "string", "description": "Tracking end date (YYYY-MM-DD). Required; must be >= startDate.", "example": "2027-06-30" } }, "required": [ "name", "startDate", "endDate" ], "additionalProperties": false }, "content-tracking_CreateProfileTrackingResponse": { "type": "object", "properties": { "trackingId": { "type": "string", "description": "Created tracking identifier.", "example": "507f1f77bcf86cd799439011" }, "name": { "type": "string", "description": "Tracking display name generated from the profile.", "example": "branduser instagram tracking" }, "status": { "type": "string", "description": "Tracking status.", "example": "active" }, "type": { "type": "string", "enum": [ "profile" ], "description": "Tracking type. Always `profile` for this endpoint.", "example": "profile" }, "startDate": { "type": "string", "description": "Tracking start instant (UTC ISO-8601).", "example": "2027-01-15T12:00:00.000Z" }, "createdFrom": { "type": "string", "description": "Origin of the tracking. Public API creates always report `api`.", "example": "api" } }, "required": [ "trackingId", "name", "status", "type", "startDate", "createdFrom" ] }, "content-tracking_CreateProfileTrackingRequest": { "type": "object", "properties": { "profileId": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "Profile ObjectId to create a profile-type content tracking for.", "example": "507f1f77bcf86cd799439011" } }, "required": [ "profileId" ], "additionalProperties": false }, "content-tracking_RemoveTrackingProfilesResponse": { "type": "object", "properties": { "trackingId": { "type": "string", "description": "Tracking identifier from the path.", "example": "507f1f77bcf86cd799439011" }, "removedProfileIds": { "type": "array", "items": { "type": "string" }, "description": "Deduplicated profile identifiers from the request. This is the accepted request list, not a confirmation of newly unlinked profiles. IDs that were not linked to the tracking may appear here.", "example": [ "507f1f77bcf86cd799439088" ] } }, "required": [ "trackingId", "removedProfileIds" ] }, "content-tracking_RemoveTrackingProfilesRequest": { "type": "object", "properties": { "profileIds": { "type": "array", "items": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "minItems": 1, "description": "Profile identifiers to remove from the tracking. Duplicate IDs are collapsed. IDs not linked to the tracking are accepted (idempotent).", "example": [ "507f1f77bcf86cd799439088" ] }, "deletePublications": { "type": "boolean", "default": false, "description": "When true, also unregisters publications of the removed profiles from the tracking. Defaults to false.", "example": false } }, "required": [ "profileIds" ], "additionalProperties": false }, "content-tracking_PauseTrackingsResponse": { "type": "object", "properties": { "pausedTrackingIds": { "type": "array", "items": { "type": "string" }, "description": "Deduplicated tracking identifiers from the request. This is the accepted request list, not a separate confirmation payload.", "example": [ "507f1f77bcf86cd799439011", "507f1f77bcf86cd799439012" ] } }, "required": [ "pausedTrackingIds" ] }, "content-tracking_PauseTrackingsRequest": { "type": "object", "properties": { "trackingIds": { "type": "array", "items": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "minItems": 1, "description": "Tracking identifiers to pause. Duplicate IDs are collapsed. All listed trackings must be ACTIVE (custom or profile type); otherwise the API returns 422.", "example": [ "507f1f77bcf86cd799439011", "507f1f77bcf86cd799439012" ] } }, "required": [ "trackingIds" ], "additionalProperties": false }, "content-tracking_ResumeTrackingsResponse": { "type": "object", "properties": { "resumedTrackingIds": { "type": "array", "items": { "type": "string" }, "description": "Deduplicated tracking identifiers from the request. This is the accepted request list, not a separate confirmation payload.", "example": [ "507f1f77bcf86cd799439011", "507f1f77bcf86cd799439012" ] } }, "required": [ "resumedTrackingIds" ] }, "content-tracking_ResumeTrackingsRequest": { "type": "object", "properties": { "trackingIds": { "type": "array", "items": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "minItems": 1, "description": "Tracking identifiers to resume. Duplicate IDs are collapsed. All listed trackings must be PAUSED (custom or profile type); otherwise the API returns 422. Resuming may also fail with 422 CONTENT_TRACKING_PROFILES_LIMIT_EXCEEDED when the brand profile quota would be exceeded.", "example": [ "507f1f77bcf86cd799439011", "507f1f77bcf86cd799439012" ] } }, "required": [ "trackingIds" ], "additionalProperties": false }, "content-tracking_ListTrackingsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/content-tracking_TrackingListItem" }, "description": "Trackings for the current page." }, "pagination": { "type": "object", "properties": { "page": { "type": "integer", "minimum": 1 }, "limit": { "type": "integer", "minimum": 1 }, "total": { "type": "integer", "minimum": 0 }, "totalPages": { "type": "integer", "minimum": 0 } }, "required": [ "page", "limit", "total", "totalPages" ], "description": "Pagination metadata." } }, "required": [ "data", "pagination" ] }, "content-tracking_TrackingListItem": { "type": "object", "properties": { "trackingId": { "type": "string", "description": "Tracking identifier.", "example": "507f1f77bcf86cd799439011" }, "name": { "type": "string", "description": "Tracking display name.", "example": "Summer Campaign" }, "status": { "type": "string", "description": "Tracking status.", "example": "active" }, "type": { "type": "string", "description": "Tracking type.", "example": "custom" }, "startDate": { "type": "string", "description": "Tracking start date.", "example": "2027-01-15T00:00:00.000Z" }, "endDate": { "type": "string", "description": "Tracking end date when set.", "example": "2027-06-30T23:59:59.999Z" }, "createdFrom": { "type": "string", "description": "Origin of the tracking.", "example": "api" } }, "required": [ "trackingId", "name", "status", "type", "startDate", "createdFrom" ] }, "content-tracking_GetTrackingPublicationsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/content-tracking_Publication" }, "description": "Publications in the tracking." }, "pagination": { "$ref": "#/components/schemas/content-tracking_PaginationMeta" } }, "required": [ "data", "pagination" ] }, "content-tracking_Publication": { "type": "object", "properties": { "publicationId": { "type": "string", "description": "Stable publication identifier. Always present.", "example": "507f1f77bcf86cd799439033" }, "network": { "type": "string", "description": "Social network of the post. Content tracking typically returns `instagram`, `tiktok`, or `youtube`. Omitted if unknown.", "example": "instagram" }, "type": { "type": "string", "description": "Post format on that network (`photo`, `reel`, `story`, `video`, `carousel`, `short`, and others). Omitted if unknown.", "example": "reel" }, "dataSource": { "type": "string", "description": "Origin of the publication. On this endpoint almost always `contentTracking`. Omitted if unknown.", "example": "contentTracking" }, "url": { "type": "string", "description": "Public permalink of the post. Omitted if unknown.", "example": "https://www.instagram.com/reel/abc" }, "shortcode": { "type": "string", "description": "Network short code or media id used in the permalink. Omitted if unknown.", "example": "abc" }, "image": { "type": "string", "description": "Cover or thumbnail image URL. Omitted if unknown.", "example": "https://cdn.example.com/image.jpg" }, "media": { "type": "array", "items": { "type": "string" }, "description": "Ordered media URLs (slides or extra assets). Omitted if none.", "example": [ "https://cdn.example.com/media1.jpg" ] }, "caption": { "type": "string", "description": "Post caption or description text. Omitted if empty.", "example": "Hello #brand @handle" }, "title": { "type": "string", "description": "Post title when the network provides one (only on YouTube / TikTok). Omitted if none.", "example": "My video title" }, "hashtags": { "type": "array", "items": { "type": "string" }, "description": "Hashtags extracted from the post. Omitted if none.", "example": [ "#brand" ] }, "mentions": { "type": "array", "items": { "type": "string" }, "description": "Mentioned handles from the post. Distinct from `tags` (people tagged on the media). Omitted if none.", "example": [ "@handle" ] }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "Keywords or topics associated with the publication content. Not the tracking filter list. Omitted if none.", "example": [ "kw" ] }, "isVideo": { "type": "boolean", "description": "True when the post is treated as video. Omitted if unknown.", "example": true }, "duration": { "type": "number", "description": "Media duration in seconds when the network provides it. Typical on Instagram Reels, TikTok video, and YouTube. Omitted if unknown.", "example": 12.5 }, "numberOfSlides": { "type": "number", "description": "Number of slides in a carousel (or 1 for a single item). Omitted if unknown.", "example": 1 }, "partnershipLabelAndAds": { "type": "string", "description": "Paid-partnership label: `sponsored` or `notCommercial`. Omitted if unknown.", "example": "sponsored" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Usernames tagged on the media (people in the photo or video). Omitted if none.", "example": [ "tagged_user" ] }, "collaborators": { "type": "array", "items": { "type": "string" }, "description": "Usernames of collaborator accounts on the post. Omitted if none.", "example": [ "collab_user" ] }, "socialNetworkStatus": { "type": "string", "description": "Lifecycle of the post on the network. For content tracking: `live`, `removed`, or `expired`. Omitted if unknown.", "example": "live" }, "internalStatus": { "type": "string", "description": "Ingestion or refresh status in Influencity: `ok`, `processing`, or `error`. Omitted if unknown.", "example": "ok" }, "publicationDate": { "type": "string", "description": "Instant the post was published, ISO 8601 UTC. Omitted if unknown.", "example": "2026-01-15T10:00:00.000Z" }, "lastUpdate": { "type": "string", "description": "Instant this publication was last refreshed by the tracking, ISO 8601 UTC. Distinct from `updatedAt`. Omitted if unknown.", "example": "2026-01-16T10:00:00.000Z" }, "createdAt": { "type": "string", "description": "Instant the publication record was created in Influencity, ISO 8601 UTC. Omitted if unknown.", "example": "2026-01-15T09:00:00.000Z" }, "updatedAt": { "type": "string", "description": "Instant the publication record was last written, ISO 8601 UTC. Omitted if unknown.", "example": "2026-01-16T10:00:00.000Z" }, "usageRights": { "type": "string", "description": "Usage-rights state: `validUntil`, `validIndefinitely`, `noUsageRights`, `expired`, or `undefined`. Omitted if unknown.", "example": "validIndefinitely" }, "usageRightsDateRangeStartDate": { "type": "string", "description": "Start of the usage-rights window, ISO 8601 UTC. Present when rights are time-bounded. Omitted otherwise.", "example": "2026-01-01T00:00:00.000Z" }, "usageRightsDateRangeEndDate": { "type": "string", "description": "End of the usage-rights window, ISO 8601 UTC. Present when `usageRights` is `validUntil`. Omitted otherwise.", "example": "2026-06-30T23:59:59.999Z" }, "likes": { "type": "number", "description": "Like count. Omitted if the network did not provide it.", "example": 10 }, "views": { "type": "number", "description": "View count. Omitted if the network did not provide it.", "example": 100 }, "comments": { "type": "number", "description": "Comment count. Omitted if the network did not provide it.", "example": 2 }, "shares": { "type": "number", "description": "Share count. Omitted if the network did not provide it.", "example": 1 }, "saves": { "type": "number", "description": "Save or bookmark count. Omitted if the network did not provide it.", "example": 3 }, "engagement": { "type": "number", "description": "Engagement rate as a percentage of the author follower count. Omitted when interactions or followers are missing.", "example": 4.2 }, "impressions": { "type": "number", "description": "Impression count. Omitted if unknown.", "example": 200 }, "reposts": { "type": "number", "description": "Repost or reuse count when provided. Omitted otherwise.", "example": 4 }, "totalInteractions": { "type": "number", "description": "Sum of interactions that have occurred on the publication. Omitted if no interaction components are present.", "example": 20 }, "externalLinkTaps": { "type": "number", "description": "Taps on an external link when provided. Omitted if unknown.", "example": 5 }, "dislikes": { "type": "number", "description": "Dislike count. Typical on YouTube. Omitted if the network did not provide it.", "example": 0 }, "estimatedViews": { "type": "number", "description": "Estimated view count when computed. Omitted otherwise.", "example": 150 }, "accountsReached": { "type": "number", "description": "Unique accounts that viewed the publication when provided. Omitted if unknown.", "example": 90 }, "accountsEngaged": { "type": "number", "description": "Unique accounts that engaged when provided. Omitted if unknown.", "example": 40 }, "follows": { "type": "number", "description": "Follows attributed to the post when provided. Omitted if unknown.", "example": 6 }, "profileVisits": { "type": "number", "description": "Profile visits attributed to the post when provided. Omitted if unknown.", "example": 7 }, "avgWatchTime": { "type": "number", "description": "Average watch time in seconds when provided. Omitted if unknown.", "example": 3.2 }, "watchTime": { "type": "number", "description": "Total watch time in seconds when provided. Omitted if unknown.", "example": 40 }, "forwards": { "type": "number", "description": "Story forwards when provided. Typical on Instagram Stories. Omitted if unknown.", "example": 1 }, "nextStory": { "type": "number", "description": "Taps to the next story when provided. Typical on Instagram Stories. Omitted if unknown.", "example": 2 }, "exited": { "type": "number", "description": "Story exits when provided. Typical on Instagram Stories. Omitted if unknown.", "example": 3 }, "replies": { "type": "number", "description": "Story or reply count when provided. Omitted if unknown.", "example": 4 }, "returningViewers": { "type": "number", "description": "Viewers who returned to the content when provided. Omitted if unknown.", "example": 5 }, "likeAndViewCountDisabled": { "type": "boolean", "description": "True when the creator hid like or view counts on the network. Typical on Instagram. Omitted if unknown.", "example": false }, "music": { "$ref": "#/components/schemas/content-tracking_PublicationMusic" }, "link": { "$ref": "#/components/schemas/content-tracking_PublicationLink" }, "quiz": { "$ref": "#/components/schemas/content-tracking_PublicationQuiz" }, "poll": { "$ref": "#/components/schemas/content-tracking_PublicationPoll" }, "question": { "type": "string", "description": "Free-text question sticker prompt. Omitted if absent.", "example": "Ask me" }, "addYours": { "$ref": "#/components/schemas/content-tracking_PublicationAddYours" }, "countdown": { "$ref": "#/components/schemas/content-tracking_PublicationCountdown" }, "donation": { "$ref": "#/components/schemas/content-tracking_PublicationDonation" }, "slider": { "$ref": "#/components/schemas/content-tracking_PublicationSlider" }, "location": { "$ref": "#/components/schemas/content-tracking_PublicationLocation" }, "profiles": { "type": "array", "items": { "$ref": "#/components/schemas/content-tracking_PublicationProfile" }, "description": "Profiles linked to the publication. Omitted if empty." }, "contentTrackings": { "type": "array", "items": { "$ref": "#/components/schemas/content-tracking_PublicationContentTrackingRef" }, "description": "Content trackings this publication belongs to. Omitted if empty." }, "campaignsV3": { "type": "array", "items": { "$ref": "#/components/schemas/content-tracking_PublicationCampaignRef" }, "description": "Linked campaign v3 references. Omitted if empty." }, "irmInfluencers": { "type": "array", "items": { "$ref": "#/components/schemas/content-tracking_PublicationIrmInfluencerRef" }, "description": "Linked IRM influencers. Omitted if empty." }, "brandClients": { "type": "array", "items": { "$ref": "#/components/schemas/content-tracking_PublicationBrandClientRef" }, "description": "Linked brand clients. Omitted if empty." } }, "required": [ "publicationId" ] }, "content-tracking_PublicationMusic": { "type": "object", "properties": { "title": { "type": "string", "description": "Track title. Omitted if unknown.", "example": "Song" }, "displayArtist": { "type": "string", "description": "Artist display name. Omitted if unknown.", "example": "Artist" }, "igUsername": { "type": "string", "description": "Instagram username of the artist, when provided. Omitted if unknown.", "example": "ig_artist" }, "igArtistFullname": { "type": "string", "description": "Instagram full name of the artist. Omitted if unknown.", "example": "IG Artist" }, "igArtistIsVerified": { "type": "boolean", "description": "Whether the Instagram artist account is verified. Omitted if unknown.", "example": true }, "author": { "type": "string", "description": "Author or composer credit. Omitted if unknown.", "example": "Author" }, "album": { "type": "string", "description": "Album name. Omitted if unknown.", "example": "Album" } }, "description": "Licensed music or audio metadata. Omitted if no audio metadata is present." }, "content-tracking_PublicationLink": { "type": "object", "properties": { "title": { "type": "string", "description": "Link-sticker label. Typical on Instagram Stories. Omitted if unknown.", "example": "Shop" }, "displayUrl": { "type": "string", "description": "Link-sticker URL shown to viewers. Omitted if unknown.", "example": "https://shop.example.com" } }, "description": "Link sticker. Omitted if absent." }, "content-tracking_PublicationQuiz": { "type": "object", "properties": { "question": { "type": "string", "description": "Quiz sticker question. Omitted if unknown.", "example": "Q?" }, "correctAnswer": { "type": "number", "description": "Index of the correct quiz option. Omitted if unknown.", "example": 0 }, "tallies": { "type": "array", "items": { "$ref": "#/components/schemas/content-tracking_PublicationLabelCount" }, "description": "Per-option vote counts. Omitted if none." } }, "description": "Quiz sticker. Omitted if absent." }, "content-tracking_PublicationLabelCount": { "type": "object", "properties": { "label": { "type": "string", "description": "Option label in a quiz or poll tally. Omitted if unknown.", "example": "Yes" }, "count": { "type": "number", "description": "Votes for that option. Omitted if unknown.", "example": 7 } } }, "content-tracking_PublicationPoll": { "type": "object", "properties": { "question": { "type": "string", "description": "Poll sticker question. Omitted if unknown.", "example": "Poll?" }, "isMultiOptionPoll": { "type": "boolean", "description": "True when multiple options can be selected. Omitted if unknown.", "example": false }, "totalVotes": { "type": "number", "description": "Total poll votes. Omitted if unknown.", "example": 10 }, "tallies": { "type": "array", "items": { "$ref": "#/components/schemas/content-tracking_PublicationLabelCount" }, "description": "Per-option vote counts. Omitted if none." } }, "description": "Poll sticker. Omitted if absent." }, "content-tracking_PublicationAddYours": { "type": "object", "properties": { "text": { "type": "string", "description": "Add Yours prompt. Omitted if unknown.", "example": "Add yours" }, "participantCount": { "type": "number", "description": "Number of Add Yours participants. Omitted if unknown.", "example": 9 } }, "description": "Add Yours sticker. Omitted if absent." }, "content-tracking_PublicationCountdown": { "type": "object", "properties": { "text": { "type": "string", "description": "Countdown sticker label. Omitted if unknown.", "example": "Soon" }, "endTime": { "type": "string", "description": "Countdown end instant, ISO 8601 UTC. Omitted if unknown.", "example": "2026-12-01T00:00:00.000Z" } }, "description": "Countdown sticker. Omitted if absent." }, "content-tracking_PublicationDonation": { "type": "object", "properties": { "contextualTitle": { "type": "string", "description": "Donation sticker contextual title. Omitted if unknown.", "example": "Donate" }, "formattedAmountRaised": { "type": "string", "description": "Amount raised, already formatted for display. Omitted if unknown.", "example": "$10" }, "formattedGoalAmount": { "type": "string", "description": "Goal amount, already formatted for display. Omitted if unknown.", "example": "$100" }, "progressStatus": { "type": "string", "description": "Fundraiser progress: `inProgress` or `ended`. Omitted if unknown.", "example": "inProgress" }, "fundraiserOwnerUsername": { "type": "string", "description": "Fundraiser owner handle. Omitted if unknown.", "example": "owner" }, "fundraiserTitle": { "type": "string", "description": "Fundraiser title. Omitted if unknown.", "example": "Cause" } }, "description": "Donation or fundraiser sticker. Omitted if absent." }, "content-tracking_PublicationSlider": { "type": "object", "properties": { "question": { "type": "string", "description": "Emoji-slider question. Omitted if unknown.", "example": "Rate" }, "emoji": { "type": "string", "description": "Emoji used on the slider. Omitted if unknown.", "example": "🔥" }, "sliderVoteAverage": { "type": "number", "description": "Average slider score when provided. Omitted if unknown.", "example": 4.5 }, "sliderVoteCount": { "type": "number", "description": "Number of slider votes. Omitted if unknown.", "example": 8 } }, "description": "Emoji slider sticker. Omitted if absent." }, "content-tracking_PublicationLocation": { "type": "object", "properties": { "name": { "type": "string", "description": "Location display name. Omitted if unknown. Coordinates are never returned.", "example": "Madrid" }, "shortName": { "type": "string", "description": "Short location label. Omitted if unknown.", "example": "MAD" }, "city": { "type": "string", "description": "City name. Omitted if unknown.", "example": "Madrid" }, "country": { "type": "string", "description": "Country name. Omitted if unknown.", "example": "Spain" }, "countryCode": { "type": "string", "description": "ISO country code. Omitted if unknown.", "example": "ES" } }, "description": "Tagged location without coordinates. Omitted if none." }, "content-tracking_PublicationProfile": { "type": "object", "properties": { "profileId": { "type": "string", "description": "Influencity profile identifier linked to the publication.", "example": "507f1f77bcf86cd799439022" }, "username": { "type": "string", "description": "Profile username. Omitted if unknown.", "example": "creator" }, "socialNetwork": { "type": "string", "description": "Profile network. Omitted if unknown.", "example": "instagram" }, "picture": { "type": "string", "description": "Profile picture URL. Omitted if unknown.", "example": "https://cdn.example.com/p.jpg" }, "isVerified": { "type": "boolean", "description": "Whether the profile is verified on the network. Omitted if unknown.", "example": true } }, "required": [ "profileId" ] }, "content-tracking_PublicationContentTrackingRef": { "type": "object", "properties": { "contentTrackingId": { "type": "string", "description": "Tracking this publication belongs to.", "example": "507f1f77bcf86cd799439011" }, "name": { "type": "string", "description": "Tracking display name. Omitted if unknown.", "example": "My Tracking" } }, "required": [ "contentTrackingId" ] }, "content-tracking_PublicationCampaignRef": { "type": "object", "properties": { "campaignId": { "type": "string", "description": "Linked campaign v3 identifier.", "example": "507f1f77bcf86cd799439044" }, "name": { "type": "string", "description": "Campaign display name. Omitted if unknown.", "example": "Campaign" } }, "required": [ "campaignId" ] }, "content-tracking_PublicationIrmInfluencerRef": { "type": "object", "properties": { "irmInfluencerId": { "type": "string", "description": "Linked IRM influencer identifier.", "example": "507f1f77bcf86cd799439055" }, "alias": { "type": "string", "description": "IRM influencer alias. Omitted if unknown.", "example": "Alias" }, "picture": { "type": "string", "description": "IRM influencer picture URL. Omitted if unknown.", "example": "https://cdn.example.com/irm.jpg" } }, "required": [ "irmInfluencerId" ] }, "content-tracking_PublicationBrandClientRef": { "type": "object", "properties": { "brandClientId": { "type": "string", "description": "Linked brand-client identifier.", "example": "507f1f77bcf86cd799439066" }, "name": { "type": "string", "description": "Brand-client display name. Omitted if unknown.", "example": "Client" } }, "required": [ "brandClientId" ] }, "content-tracking_PaginationMeta": { "type": "object", "properties": { "page": { "type": "integer", "description": "Current 1-based page.", "example": 1 }, "limit": { "type": "integer", "description": "Page size.", "example": 20 }, "total": { "type": "integer", "description": "Total matching publications.", "example": 150 }, "totalPages": { "type": "integer", "description": "Total pages.", "example": 8 } }, "required": [ "page", "limit", "total", "totalPages" ] }, "content-tracking_GetTrackingQuotaResponse": { "type": "object", "properties": { "remainingProfilesInTracking": { "type": "integer", "nullable": true, "description": "Remaining profile slots that can be linked to active content trackings for the authenticated brand. This counts profiles across content trackings (and legacy Reports V2 trackings when applicable). This is not IRM analysis quota (`GET /v1/profiles/quota`). null when unlimited.", "example": 42 }, "profilesLimit": { "type": "integer", "nullable": true, "description": "Maximum profile slots allowed in content tracking for the authenticated brand. This is not the number of tracking campaigns (`reportsV2.trackingLimit`) nor IRM analysis quota. null when unlimited.", "example": 100 } }, "required": [ "remainingProfilesInTracking", "profilesLimit" ], "description": "Content tracking profile-slot quota for the authenticated brand. Applies when linking profiles to trackings, not when analyzing profiles." }, "content-tracking_AddTrackingProfilesResponse": { "type": "object", "properties": { "trackingId": { "type": "string", "description": "Tracking identifier from the path.", "example": "507f1f77bcf86cd799439011" }, "addedProfileIds": { "type": "array", "items": { "type": "string" }, "description": "Deduplicated profile identifiers from the request. This is the accepted request list, not a confirmation of newly persisted links. IDs already linked to the tracking may appear here.", "example": [ "507f1f77bcf86cd799439088" ] } }, "required": [ "trackingId", "addedProfileIds" ] }, "content-tracking_AddTrackingProfilesRequest": { "type": "object", "properties": { "profileIds": { "type": "array", "items": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "minItems": 1, "description": "Profile identifiers to attach to the tracking. Duplicate IDs are collapsed. Profiles already linked to the tracking are accepted (idempotent).", "example": [ "507f1f77bcf86cd799439088" ] } }, "required": [ "profileIds" ], "additionalProperties": false }, "content-tracking_RefreshTrackingResponse": { "type": "object", "properties": { "trackingId": { "type": "string", "description": "Tracking identifier from the path.", "example": "507f1f77bcf86cd799439011" }, "status": { "type": "string", "enum": [ "queued" ], "description": "Refresh was accepted and queued for processing.", "example": "queued" } }, "required": [ "trackingId", "status" ] }, "content-tracking_ApiError": { "type": "object", "description": "Machine-readable error code and human-readable message.", "properties": { "code": { "type": "string", "description": "Stable error identifier for programmatic handling." }, "message": { "type": "string", "description": "Short explanation of the failure." }, "details": { "type": "object", "description": "Optional structured context (for example validation field errors).", "additionalProperties": true } }, "required": [ "code", "message" ] }, "content-tracking_ApiErrorResponse": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/content-tracking_ApiError" } }, "required": [ "error" ] }, "profiles_HealthResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ], "description": "Service health status.", "example": "ok" }, "service": { "type": "string", "description": "Service name.", "example": "profiles" }, "stage": { "type": "string", "description": "Deployment stage.", "example": "dev" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO timestamp generated by the service.", "example": "2026-07-22T12:00:00.000Z" } }, "required": [ "status", "service", "stage", "timestamp" ] }, "profiles_AddProfileResponse": { "type": "object", "properties": { "profileId": { "type": "string", "description": "Profile identifier.", "example": "507f1f77bcf86cd799439011" }, "username": { "type": "string", "description": "Normalized profile username.", "example": "influencity" }, "socialNetwork": { "type": "string", "description": "Social network of the created profile.", "example": "instagram" }, "url": { "type": "string", "format": "uri", "description": "Public profile URL.", "example": "https://www.instagram.com/influencity" }, "status": { "type": "string", "enum": [ "new", "update", "autoRefresh", "ok", "notAnalyzed", "lessThan1000", "noAudienceDataAvailable", "private", "notExists", "ko", "retry_later", "incompletedData" ], "description": "Profile analysis status. Present when the request included `analyze: true`.", "example": "new" }, "isAnalyzing": { "type": "boolean", "description": "Whether the profile analysis is still in progress. Present when the request included `analyze: true`.", "example": true } }, "required": [ "profileId", "username", "socialNetwork", "url" ] }, "profiles_AddProfileConflictError": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/profiles_AddProfileConflictErrorBody" } }, "required": [ "error" ] }, "profiles_AddProfileConflictErrorBody": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "IRM_PROFILE_DUPLICATED" ], "description": "Stable error identifier for a duplicate profile.", "example": "IRM_PROFILE_DUPLICATED" }, "message": { "type": "string", "description": "Short explanation of the failure.", "example": "Profile already exists" }, "details": { "$ref": "#/components/schemas/profiles_AddProfileConflictDetails" } }, "required": [ "code", "message" ] }, "profiles_AddProfileConflictDetails": { "type": "object", "properties": { "profileId": { "type": "string", "description": "Identifier of the existing profile for this brand. Clients can use it to retrieve the profile with GET /v1/profiles/{profileId} instead of creating a duplicate.", "example": "507f1f77bcf86cd799439011" } }, "required": [ "profileId" ], "description": "Present when the existing profile identifier is known. Omitted if the upstream conflict payload has no id." }, "profiles_AddProfileRequest": { "type": "object", "properties": { "socialNetwork": { "type": "string", "enum": [ "instagram", "youtube", "tiktok", "twitter", "facebook", "snapchat", "tumblr", "twitch", "vk", "weibo", "pinterest", "douyin" ], "description": "Social network of the profile to add. Any IRM network is accepted; analysis is only available for instagram, tiktok, youtube, twitch.", "example": "instagram" }, "profile": { "type": "string", "minLength": 1, "description": "Profile username or public URL.", "example": "influencity" }, "analyze": { "type": "boolean", "description": "When true, queues an audience analysis for the profile. Only supported on instagram, tiktok, youtube, twitch. The response is returned immediately with `isAnalyzing: true` while analysis runs asynchronously.", "example": true } }, "required": [ "socialNetwork", "profile" ] }, "profiles_GetProfileResponse": { "type": "object", "properties": { "profileId": { "type": "string", "description": "Profile identifier.", "example": "507f1f77bcf86cd799439011" }, "username": { "type": "string", "description": "Normalized profile username.", "example": "influencity" }, "socialNetwork": { "type": "string", "description": "Social network of the profile.", "example": "instagram" }, "url": { "type": "string", "format": "uri", "description": "Public profile URL derived from social network and username.", "example": "https://www.instagram.com/influencity" }, "status": { "type": "string", "description": "Analysis status key (for example `ok`, `update`, `new`, `notAnalyzed`).", "example": "ok" }, "isAnalyzing": { "type": "boolean", "description": "True when the profile analysis or refresh is in progress.", "example": false }, "lastUpdatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "ISO-8601 timestamp of the last profile data refresh (from upstream `lastRefreshDate`), or null if unknown.", "example": "2026-01-15T10:00:00.000Z" }, "profilePhotoUrl": { "type": "string", "format": "uri", "description": "Public profile photo URL when present upstream.", "example": "https://cdn.example.com/photo.jpg" }, "originalSource": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "How the profile entered IRM." }, "followerCount": { "type": "number", "description": "Current followers (Instagram/TikTok/Twitch) or subscribers (YouTube)." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp when the profile was created for the brand.", "example": "2026-02-01T08:30:00.000Z" }, "audienceTopGender": { "$ref": "#/components/schemas/profiles_ProfileKeyValuePair" }, "audienceTopAge": { "allOf": [ { "$ref": "#/components/schemas/profiles_ProfileKeyValuePair" }, { "description": "Largest age band of followers, plus its percentage." } ] }, "audienceTopCountry": { "$ref": "#/components/schemas/profiles_ProfileLabelValuePair" }, "audienceTopCity": { "$ref": "#/components/schemas/profiles_ProfileCompleteNameValuePair" }, "likersTopGender": { "allOf": [ { "$ref": "#/components/schemas/profiles_ProfileKeyValuePair" }, { "description": "Largest gender slice among likers. Instagram-oriented." } ] }, "likersTopAge": { "allOf": [ { "$ref": "#/components/schemas/profiles_ProfileKeyValuePair" }, { "description": "Largest age band among likers, plus its percentage. Instagram-oriented." } ] }, "likersTopCountry": { "allOf": [ { "$ref": "#/components/schemas/profiles_ProfileLabelValuePair" }, { "description": "Country with the most likers. Instagram-oriented." } ] }, "likersTopCity": { "allOf": [ { "$ref": "#/components/schemas/profiles_ProfileCompleteNameValuePair" }, { "description": "City with the most likers. Shown as \"City, Country\" plus percentage. Instagram-oriented." } ] }, "accountType": { "type": "string", "description": "Instagram account type (Business, Creator, Personal)." }, "streamChannelType": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "Twitch channel persona (male, female, organization)." }, "streamTopCategory": { "allOf": [ { "$ref": "#/components/schemas/profiles_ProfileLabelValuePair" }, { "description": "Game or category that accounts for the most watched hours." } ] }, "gender": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "Last known or inferred gender of the author." }, "age": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "Detected age band of the creator." }, "language": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "Detected language of the creator." }, "totalViews": { "type": "number", "description": "Lifetime video views. Populated on YouTube." }, "postNumber": { "type": "number", "description": "Number of posts or videos." }, "avgLikes": { "type": "number", "description": "Average likes per content piece." }, "avgDislikes": { "type": "number", "description": "Average dislikes per video. YouTube only." }, "avgComments": { "type": "number", "description": "Average comments per content piece." }, "avgViews": { "type": "number", "description": "Average views per video. Used on TikTok, YouTube and Twitch." }, "totalLikes": { "type": "number", "description": "Lifetime likes on the account. TikTok only." }, "avgReelsPlays": { "type": "number", "description": "Average Instagram Reels plays. Instagram only." }, "city": { "type": "string", "description": "Creator's city." }, "state": { "type": "string", "description": "Creator's state or region." }, "country": { "type": "string", "description": "Creator's country." }, "audienceTopEthnicity": { "allOf": [ { "$ref": "#/components/schemas/profiles_ProfileKeyValuePair" }, { "description": "Largest ethnicity slice of followers." } ] }, "likersTopEthnicity": { "allOf": [ { "$ref": "#/components/schemas/profiles_ProfileKeyValuePair" }, { "description": "Largest ethnicity among likers." } ] }, "audienceTopLanguage": { "allOf": [ { "$ref": "#/components/schemas/profiles_ProfileKeyValuePair" }, { "description": "Language most spoken by followers." } ] }, "likersTopLanguage": { "allOf": [ { "$ref": "#/components/schemas/profiles_ProfileKeyValuePair" }, { "description": "Language most spoken by likers." } ] }, "audienceTopBrandAffinity": { "allOf": [ { "$ref": "#/components/schemas/profiles_ProfileLabelValuePair" }, { "description": "Brand the followers overlap with most." } ] }, "likersTopBrandAffinity": { "allOf": [ { "$ref": "#/components/schemas/profiles_ProfileLabelValuePair" }, { "description": "Brand likers overlap with most." } ] }, "audienceTopInterest": { "allOf": [ { "$ref": "#/components/schemas/profiles_ProfileLabelValuePair" }, { "description": "Strongest interest among followers." } ] }, "likersTopInterest": { "allOf": [ { "$ref": "#/components/schemas/profiles_ProfileLabelValuePair" }, { "description": "Strongest interest among likers." } ] }, "audienceTopState": { "allOf": [ { "$ref": "#/components/schemas/profiles_ProfileLabelValuePair" }, { "description": "State/region with the most followers." } ] }, "createdByUser": { "type": "string", "description": "First name of the user who created the profile.", "example": "Alejandro" }, "profileInterests": { "type": "array", "items": { "type": "string" }, "description": "Localized profile interest labels.", "example": [ "Clothes, Shoes, Handbags & Accessories" ] }, "fullName": { "type": "string", "description": "Display name of the profile.", "example": "Ibai Llanos" }, "isVerified": { "type": "boolean", "description": "True when the social network marks the profile as verified.", "example": true }, "followingCount": { "type": "number", "description": "Number of accounts the profile follows.", "example": 616 }, "private": { "type": "boolean", "description": "True when the social profile is private.", "example": false }, "analyzeProfile": { "type": "boolean", "description": "True when the profile has been submitted for analysis.", "example": true }, "noAudienceDataAvailable": { "type": "boolean", "description": "True when audience insights are not available for the profile.", "example": false }, "streamPartnershipStatus": { "nullable": true, "description": "Streaming partnership status when available." }, "hasFollowersData": { "type": "boolean", "description": "True when follower audience insights are available.", "example": true }, "hasLikersData": { "type": "boolean", "description": "True when liker audience insights are available.", "example": true }, "metrics": { "$ref": "#/components/schemas/profiles_GetProfileMetrics" } }, "required": [ "profileId", "username", "socialNetwork", "url", "status", "isAnalyzing", "lastUpdatedAt" ] }, "profiles_ProfileKeyValuePair": { "type": "object", "properties": { "key": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "nullable": true } ], "example": "Men" }, "value": { "type": "number", "nullable": true, "example": 50.09 } }, "description": "Largest gender slice of followers." }, "profiles_ProfileLabelValuePair": { "type": "object", "properties": { "label": { "type": "string", "nullable": true, "example": "Peru" }, "value": { "type": "number", "nullable": true, "example": 78.01 } }, "description": "Country with the most followers." }, "profiles_ProfileCompleteNameValuePair": { "type": "object", "properties": { "completeName": { "type": "string", "nullable": true, "example": "Lima, Peru" }, "value": { "type": "number", "nullable": true, "example": 37.93 } }, "description": "City with the most followers. Shown as \"City, Country\" plus percentage." }, "profiles_GetProfileMetrics": { "type": "object", "properties": { "ages": { "nullable": true, "description": "Follower age distribution, determined by analyzing profile photos and selfies in recent posts." }, "genderGraph": { "nullable": true, "description": "Follower gender distribution, determined by analyzing profile photos as well as name, bio, and selfies in recent posts. Items are `{ gender, percentage }`." }, "generateTopics": { "nullable": true, "description": "Topic labels for the influencer, audience, and likers, determined by analyzing captions, mentions, hashtags, and location tags in recent posts." }, "geo": { "nullable": true, "description": "Follower geography (countries and cities), determined by analyzing location tags, language, captions in recent posts, and profile bios. Country entries may include geometry coordinates." }, "influenceGraph": { "nullable": true, "description": "Influencer credibility signals used to compare account quality, such as avatar, bio, post volume, and follow ratios." }, "hashtags": { "nullable": true, "description": "Top hashtags used by the profile, determined by analyzing recent post captions." }, "mentions": { "nullable": true, "description": "Top mentioned accounts, determined by analyzing recent post captions to see who the influencer has interacted with." }, "agesByGender": { "nullable": true, "description": "Follower age distribution segmented by gender, determined by analyzing profile photos and selfies in recent posts." }, "avgInteractions": { "nullable": true, "description": "Average number of likes, comments, and replies on one post, based on interactions in recent posts." }, "avgInteractionsBy30Posts": { "nullable": true, "description": "Average interactions calculated over the last 30 posts." }, "influencerBrandAffinity": { "nullable": true, "description": "Brands the influencer mentions or has an affinity with, determined by analyzing captions, mentions, hashtags, and location tags in recent posts." }, "audienceBrandAffinity": { "nullable": true, "description": "Brands the follower audience has an affinity with, determined by analyzing captions, mentions, hashtags, and location tags in recent audience posts." }, "totalKPIs": { "nullable": true, "description": "Aggregated KPI totals such as engagement and earned media, used to compare profile quality. On Twitch this may include stream KPIs." }, "followersStats": { "nullable": true, "description": "Follower growth and quality statistics, including how the follower count has changed over time." }, "averageLikesStats": { "nullable": true, "description": "Like statistics over time, based on likes received on recent posts." }, "averageViewsStats": { "nullable": true, "description": "View statistics over time, based on views received on recent posts or videos." }, "audienceLanguages": { "nullable": true, "description": "Follower language distribution, determined by analyzing captions of recent posts. Graph items keep `{ key, label, value }`." }, "audienceEthnicities": { "nullable": true, "description": "Follower ethnicity distribution, determined by analyzing profile pictures, bio text, and selfies in recent posts. Shown as an aggregated percentage." }, "audienceReachability": { "nullable": true, "description": "Share of followers grouped by how many accounts they follow (more than 1,500; 1,000–1,500; 500–1,000; and fewer than 500). Accounts following more than 1,500 accounts are less likely to see sponsored posts." }, "audienceLookalikes": { "nullable": true, "description": "Accounts with similar audience demographics. This information is updated every 3 months." }, "notableFollowers": { "nullable": true, "description": "Top followers with more than 1,000 followers. This information is updated every 3 months." }, "engagement": { "nullable": true, "description": "Average interactions on recent posts divided by the number of followers." }, "topPosts": { "nullable": true, "description": "Sample of best-performing posts, based on recent activity such as likes, comments, and views." }, "sponsoredPosts": { "nullable": true, "description": "Detected sponsored content, identified from commercial hashtags or official paid-partnership tags." }, "topReels": { "nullable": true, "description": "Best-performing Reels, based on recent plays and interactions." }, "sponsoredPostsEngagementRatio": { "nullable": true, "description": "Performance of sponsored posts compared with organic posts. For example, 10% means paid posts are performing 10% worse than organic posts." }, "notableFollowersRatio": { "nullable": true, "description": "Percentage of followers that are notable (influencers). Notable followers for a 0.99 quantile can range from about 1% to 20%." }, "followingStats": { "nullable": true, "description": "Number of accounts followed and how that following behavior has changed over time." }, "influencerLookalikes": { "nullable": true, "description": "Profiles with similar content. This information is updated every 3 months." }, "influencerGrowthStats": { "nullable": true, "description": "Historical follower growth, including new followers gained over time." }, "likers": { "nullable": true, "description": "Audience graphs for users who liked the profile content, including geo, gender, ages, affinities, and notable likers." }, "streamAverageViewDuration": { "nullable": true, "description": "Average time that unique viewers watch a stream, game, or channel." }, "streamUniqueViewers": { "nullable": true, "description": "Estimated number of unique individuals who watched a stream, game, or channel in the period, based on unique authorized viewers and the authorized-to-all-viewers ratio." }, "streamEstimateIncome": { "nullable": true, "description": "Approximate earnings from current active paid subscriptions, calculated for several pricing scenarios." }, "streamContentAuthorized": { "nullable": true, "description": "Percentage of viewers who are authorized or logged in during the stream. A higher ratio means a more accurate unique-viewers estimate." }, "streamSubscribedType": { "nullable": true, "description": "Breakdown of viewers by subscription type." }, "streamActiveSubsByTier": { "nullable": true, "description": "Active paid subscriptions grouped by tier." }, "streamTopGames": { "nullable": true, "description": "Games or categories ranked by hours watched." }, "streamChatKPIs": { "nullable": true, "description": "Chat activity during streams, such as messages, active chatters, and related KPIs." }, "streamAdditionalStats": { "nullable": true, "description": "Additional chat and stream performance statistics, such as average messages and bits." }, "streamChatterWith": { "nullable": true, "description": "Active chatters who sent 1 message versus those who sent 2 or more messages during the stream." }, "streamCheersAndBits": { "nullable": true, "description": "Cheers and bits activity, including totals and estimated income from bits." }, "estimatedViews": { "nullable": true, "description": "Estimated number of times a post may be seen, based on followers, engagement, and past reach of similar content." }, "estimatedStoryViews": { "nullable": true, "description": "Estimated number of times the stories of this profile are likely to be seen, based on follower count, engagement rate, and historical reach of similar content." }, "estimatedPostPriceMin": { "nullable": true, "description": "Estimated minimum cost for a sponsored feed post. Numeric value. Instagram only; empty for other networks or profiles not analyzed after the new pricing model rollout." }, "estimatedPostPriceMedium": { "nullable": true, "description": "Estimated median cost for a sponsored feed post. Numeric value. Non-Instagram networks may only expose this field and related CPM metrics." }, "estimatedPostPriceMax": { "nullable": true, "description": "Estimated maximum cost for a sponsored feed post. Numeric value. Instagram only; empty for other networks or profiles not analyzed after the new pricing model rollout." }, "estimatedPostCPM": { "nullable": true, "description": "Estimated CPM for a feed post (cost per 1,000 estimated post views). Numeric value. May be empty when views are unavailable." }, "estimatedStoryPriceMin": { "nullable": true, "description": "Estimated minimum cost for a sponsored story. Numeric value. Instagram only; empty for other networks or profiles not analyzed after the new pricing model rollout." }, "estimatedStoryPriceMedium": { "nullable": true, "description": "Estimated median cost for a sponsored story. Numeric value. Instagram only; empty for other networks or profiles not analyzed after the new pricing model rollout." }, "estimatedStoryPriceMax": { "nullable": true, "description": "Estimated maximum cost for a sponsored story. Numeric value. Instagram only; empty for other networks or profiles not analyzed after the new pricing model rollout." }, "estimatedStoryCPM": { "nullable": true, "description": "Estimated CPM for a story (cost per 1,000 estimated story views). Numeric value. Instagram only; may be empty when story views are unavailable." }, "estimatedReelPriceMin": { "nullable": true, "description": "Estimated minimum cost for a sponsored reel. Numeric value. Instagram only; empty for other networks or profiles not analyzed after the new pricing model rollout." }, "estimatedReelPriceMedium": { "nullable": true, "description": "Estimated median cost for a sponsored reel. Numeric value. Instagram only; empty for other networks or profiles not analyzed after the new pricing model rollout." }, "estimatedReelPriceMax": { "nullable": true, "description": "Estimated maximum cost for a sponsored reel. Numeric value. Instagram only; empty for other networks or profiles not analyzed after the new pricing model rollout." }, "estimatedReelCPM": { "nullable": true, "description": "Estimated CPM for a reel (cost per 1,000 average reel plays). Numeric value. Instagram only; may be empty when reel play data is unavailable." }, "estimatedMedianCPM": { "nullable": true, "description": "Estimated median CPM for the profile. On Instagram, the arithmetic mean of the format CPMs that could be calculated (feed post, story, and reel); formats without a CPM are excluded. On other networks, the same value as the feed post CPM. Numeric value. Used to compare efficiency between profiles. May be empty when no format CPM is available." }, "engagementByViews": { "nullable": true, "description": "Percentage of viewers who actively engage with the content. On Instagram: likes and comments on estimated viewers. On TikTok: likes, comments, and saves. On YouTube: likes and comments. On Twitch: chat messages during the stream." } }, "additionalProperties": { "nullable": true }, "description": "Audience, content, and estimate metrics when analysis data is available." }, "profiles_DeleteProfileResponse": { "type": "object", "properties": { "profileId": { "type": "string", "description": "Deleted profile identifier.", "example": "507f1f77bcf86cd799439011" } }, "required": [ "profileId" ] }, "profiles_GetProfilesQuotaResponse": { "type": "object", "properties": { "remainingAnalysisPerPeriod": { "type": "integer", "nullable": true, "description": "Remaining profile analyses available in the current period (analyze or refresh). This is not the quota for adding profiles without analysis. null when unlimited.", "example": 42 }, "analysisLimitPerPeriod": { "type": "integer", "nullable": true, "description": "Maximum profile analyses allowed in the current period (analyze or refresh). This is not the quota for adding profiles without analysis. null when unlimited.", "example": 100 } }, "required": [ "remainingAnalysisPerPeriod", "analysisLimitPerPeriod" ], "description": "IRM profile analysis quota for the authenticated brand. Counts analyze/refresh operations, not profile additions." }, "profiles_AnalyzeProfileResponse": { "anyOf": [ { "$ref": "#/components/schemas/profiles_AnalyzeProfileQueuedResponse" }, { "$ref": "#/components/schemas/profiles_GetProfileResponse" } ] }, "profiles_AnalyzeProfileQueuedResponse": { "type": "object", "properties": { "profileId": { "type": "string", "description": "Profile identifier from the path.", "example": "507f1f77bcf86cd799439011" }, "status": { "type": "string", "enum": [ "update" ], "description": "Queued analysis status reported by the upstream service.", "example": "update" }, "isAnalyzing": { "type": "boolean", "enum": [ true ], "description": "Indicates the profile analysis is in progress.", "example": true } }, "required": [ "profileId", "status", "isAnalyzing" ] }, "profiles_RefreshProfileResponse": { "type": "object", "properties": { "profileId": { "type": "string", "description": "Profile identifier from the path.", "example": "507f1f77bcf86cd799439011" }, "status": { "type": "string", "enum": [ "update" ], "description": "Queued refresh status reported by the upstream service.", "example": "update" }, "isRefreshing": { "type": "boolean", "enum": [ true ], "description": "Indicates the profile refresh is in progress.", "example": true } }, "required": [ "profileId", "status", "isRefreshing" ] }, "profiles_ApiError": { "type": "object", "description": "Machine-readable error code and human-readable message.", "properties": { "code": { "type": "string", "description": "Stable error identifier for programmatic handling." }, "message": { "type": "string", "description": "Short explanation of the failure." }, "details": { "type": "object", "description": "Optional structured context (for example validation field errors).", "additionalProperties": true } }, "required": [ "code", "message" ] }, "profiles_ApiErrorResponse": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/profiles_ApiError" } }, "required": [ "error" ] } }, "securitySchemes": { "BearerApiToken": { "type": "http", "scheme": "bearer", "description": "Influencity API token issued to your organization. Use `Authorization: Bearer `." } }, "parameters": {} } }