Endpoints

POST /api/v1/resources/search

Retrieve metrics for one or more social media resources.

Request Body

{
  "resources": [
    {
      "platform": "instagram",
      "type": "account",
      "identifier": "natgeo"
    }
  ]
}

Fields

Field	Type	Required	Description
resources	array	yes	List of resources to query
resources[].platform	string	yes	Platform code — facebook, instagram, linkedin, threads, tiktok, x, or youtube
resources[].type	string	yes	Resource type — account
resources[].identifier	string	yes	Username or ID to look up

Constraints

• Maximum 10 resources per request
• Duplicate resources (same platform + type + identifier) are automatically removed

Example Request

curl -X POST https://metrika.run/api/v1/resources/search \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "resources": [
      {"platform": "instagram", "type": "account", "identifier": "natgeo"},
      {"platform": "instagram", "type": "account", "identifier": "nasa"}
    ]
  }'

Success Response

200 OK

{
  "data": [
    {
      "platform": "instagram",
      "identifier": "natgeo",
      "status": "available",
      "metrics": {
        "followers": {
          "value": 284000000,
          "status": "available"
        }
      }
    },
    {
      "platform": "instagram",
      "identifier": "nasa",
      "status": "available",
      "metrics": {
        "followers": {
          "value": 96800000,
          "status": "available"
        }
      }
    }
  ]
}

The data array contains one entry per requested resource in the same order as the request. If a resource cannot be resolved (e.g. username not found), its metric values will be null.

The status field at the resource level indicates the availability of the social account:

Status	Description
available	The social account was found and data is being collected
pending	Data collection for this account is in progress
not_found	The account could not be found on the platform
unavailable	The account is not available for this platform

The status field inside each metric indicates the availability of the data:

Status	Description
available	Metric data is current and ready
unavailable	Metric is not available for this platform
pending	Metric is being collected and will be available soon

Error Responses

Unauthorized

401 Unauthorized

The request did not include a valid API token. Include it in the Authorization: Bearer header.

Validation Error

422 Unprocessable Entity

{
  "errors": [
    "'resources' field is required"
  ]
}

The request body failed validation. The errors array contains one or more descriptive messages.

Rate Limited

429 Too Many Requests

The rate limit for this account has been exceeded. Paid subscriptions reset every minute; free-tier access resets every 30 days.

Error Code Reference

Status	Description
200	Success
401	Missing or invalid API token
422	Request validation failed
429	Rate limit exceeded
500	Internal server error