Collect and read mentions

This guide starts scraping for a project keyword and retrieves the resulting mentions.

Prerequisites

• A bearer access token
• A project created with POST /api/project
• The identifier used by the deployed backend as the keyword ID

The current app flow uses the project's data.id as that keyword ID, but the Swagger terminology does not formally define this mapping.

1. Start scraping

Pass the keyword ID as keyword_id:

curl -X POST \
  "$SOCIOVITE_API_URL/api/ai-service/scrap-project-keywords" \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "keyword_id": "keyword_id"
  }'

Swagger guarantees only this response shape:

{
  "success": true,
  "result": {}
}

result is not typed in the contract.

Collection readiness

The supplied Swagger does not expose a scraping task ID, job-status endpoint, or completion callback. It therefore does not specify when mentions become available after this call.

2. Optionally inspect the content count

curl \
  "$SOCIOVITE_API_URL/api/project/content-count?id=project_id" \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <access_token>'

Example response:

{
  "data": 43
}

The count endpoint uses an id described by Swagger as a project ID. Do not assume it is a formal scraping-status signal.

3. Retrieve the first page

The mentions endpoint requires keywordId:

curl \
  "$SOCIOVITE_API_URL/api/mentions?keywordId=keyword_id&page=1&limit=10" \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <access_token>'

Example 200 OK response:

{
  "data": [
    {
      "id": "mention_id",
      "targeted_account_id": "account_id",
      "content": "A post that matched the monitored keyword.",
      "keywordid": "keyword_id",
      "url": "https://social.example/posts/123",
      "sentimen": 1,
      "socialmediaid": "social_media_id",
      "createdat": "2026-07-20T08:30:00Z",
      "updated_at": "2026-07-20T08:35:00Z",
      "targeted_account": {
        "username": "account_username",
        "display_name": "Account Name"
      },
      "SnaKeyword": {
        "group": "Acme July Monitoring",
        "keyword": "acme"
      }
    }
  ],
  "total": 43,
  "page": 1,
  "limit": 10,
  "totalPages": 5
}

4. Read all pages

Start at page=1 and increment page until it reaches totalPages. limit defaults to 10; Swagger's parameter description states a maximum of 100.

Optional filters:

Parameter	Type	Purpose
sentimen	integer	Filter by sentiment code
sosmedId	string	Filter by social-media source ID

Swagger does not define the allowed source IDs or the meaning of each sentiment code. Obtain those mappings from the backend before presenting human-readable labels.

Troubleshooting

Symptom	Check
400 Bad Request	keywordId is required and casing matters.
Empty data	The contract does not define readiness; verify scraping and the identifier mapping.
500 Internal Server Error	Record the request parameters and inspect backend logs.

See the full AI Service and Mentions references.