> ## Documentation Index > Fetch the complete documentation index at: https://docs.api.tamtam.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create an engagement watch > Watch LinkedIn posts and collect the people who engage with them as leads. Two kinds. A **topic** watch takes a boolean keyword query (`"lean manufacturing" OR "visual management"`) and surfaces whoever liked the matching posts. A **company** watch does the same for one competitor's own posts — people interacting with a competitor are, by definition, shopping in your category. Set `persona_ids` to decide who counts as a lead; the personas are the ones from [List personas](/api-reference/personas/list-personas), so sharpening a persona sharpens every watch using it. Engagers matching no persona are still recorded, so widening a persona later surfaces people already collected rather than only affecting future sweeps. **Cost is `max_posts_per_sweep` × `max_engagers_per_post` per sweep**, and nothing else. Both default conservatively; raise them once a watch is producing what you expect. A watch's kind and target are fixed once created: pointing it somewhere else would leave its collected people describing a subject it no longer has, so create a second watch instead. ## OpenAPI ````yaml /reference/openapi.yaml post /v2/engagement-watches openapi: 3.1.0 info: title: Tamtam Public API version: 2.0.0 servers: - url: https://api.tamtam.ai/api security: [] paths: /v2/engagement-watches: post: tags: - Engagement Watches summary: Create an engagement watch description: >- Watch LinkedIn posts and collect the people who engage with them as leads. Two kinds. A **topic** watch takes a boolean keyword query (`"lean manufacturing" OR "visual management"`) and surfaces whoever liked the matching posts. A **company** watch does the same for one competitor's own posts — people interacting with a competitor are, by definition, shopping in your category. Set `persona_ids` to decide who counts as a lead; the personas are the ones from [List personas](/api-reference/personas/list-personas), so sharpening a persona sharpens every watch using it. Engagers matching no persona are still recorded, so widening a persona later surfaces people already collected rather than only affecting future sweeps. **Cost is `max_posts_per_sweep` × `max_engagers_per_post` per sweep**, and nothing else. Both default conservatively; raise them once a watch is producing what you expect. A watch's kind and target are fixed once created: pointing it somewhere else would leave its collected people describing a subject it no longer has, so create a second watch instead. operationId: create-engagement-watch parameters: - description: >- Target account UUID. Required for staff callers; ignored for customer API keys. explode: false in: query name: account_id schema: description: >- Target account UUID. Required for staff callers; ignored for customer API keys. type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateEngagementWatchBody' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/EngagementWatchDto' description: OK default: content: application/problem+json: schema: $ref: '#/components/schemas/ErrorModel' description: Error security: - apikeyAuth: [] - bearerAuth: [] components: schemas: CreateEngagementWatchBody: additionalProperties: false properties: company_linkedin_id: description: >- Required for kind=company, and rejected for kind=topic. The competitor's numeric LinkedIn ID. type: string countries: description: >- ISO 3166-1 alpha-2 codes to keep. Omit for no country restriction. This filters engagers; it is never written onto them. items: type: string type: - array - 'null' is_enabled: description: Defaults to true. type: boolean keywords: description: >- Required for kind=topic, and rejected for kind=company. A LinkedIn boolean query, passed through as written: "lean manufacturing" OR "visual management". type: string kind: description: topic or company. enum: - topic - company type: string max_engagers_per_post: description: >- How many engagers are read per post. Defaults to 25. Spend per sweep is this times max_posts_per_sweep. format: int32 maximum: 500 minimum: 1 type: integer max_posts_per_sweep: description: How many posts one sweep looks at. Defaults to 10. format: int32 maximum: 100 minimum: 1 type: integer name: description: Your label for this watch. minLength: 1 type: string persona_ids: description: >- Personas deciding which engagers count as leads, from GET /v2/personas. Omit to keep everyone who engaged. Engagers matching none are still recorded, so widening a persona later surfaces people already collected. items: type: string type: - array - 'null' required: - kind - name type: object EngagementWatchDto: additionalProperties: false properties: company_linkedin_id: description: 'Company watches only: the competitor''s numeric LinkedIn ID.' type: string countries: description: >- ISO 3166-1 alpha-2 codes to keep. Empty means no country restriction. items: type: string type: - array - 'null' created_at: format: date-time type: string id: type: string is_enabled: description: >- A disabled watch is not swept and costs nothing, but keeps its history. type: boolean keywords: description: 'Topic watches only: the boolean query, exactly as you wrote it.' type: string kind: description: topic or company. examples: - topic type: string last_sweep_engagers_collected: description: >- How many people the last run collected. Zero after a completed sweep means nobody engaged, which is different from the watch not having run. format: int32 type: integer last_sweep_outcome: description: >- What the last run did. One of: - completed: it ran, and last_sweep_engagers_collected says what it found. Zero is a real answer. - out_of_credits: skipped before spending, because the account could not pay for a single person. **This is the one to check when a feed goes quiet** — topping up resumes it on the next sweep. - failed: it ran and something went wrong, usually the provider. Self-correcting, since the next sweep re-reads an overlapping window. type: string last_swept_at: description: When this watch last ran. Absent until its first sweep. format: date-time type: string max_engagers_per_post: description: >- Cost dial: how many engagers are read per post. Spend per sweep is this times max_posts_per_sweep. format: int32 type: integer max_posts_per_sweep: description: 'Cost dial: how many posts one sweep will look at.' format: int32 type: integer name: description: Your label for this watch. examples: - Lean manufacturing type: string persona_ids: description: >- Personas that decide which engagers count as leads. Empty keeps everyone who engaged. items: type: string type: - array - 'null' updated_at: format: date-time type: string required: - id - kind - name - countries - persona_ids - max_posts_per_sweep - max_engagers_per_post - is_enabled - created_at - updated_at type: object ErrorModel: additionalProperties: false properties: detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object securitySchemes: apikeyAuth: description: Account API key passed in the Authorization header in: header name: Authorization type: apiKey bearerAuth: description: Bearer JWT obtained via the OAuth 2.1 authorization flow scheme: bearer type: http ````