# Scraper Results

Source: https://recoupable.dev/docs/api-reference/apify/scraper

Check the status and retrieve results from Apify scraper runs. This endpoint uses the Apify API Client to fetch the current status of a scraper run and its results if available. Use the runId returned from endpoints like Instagram Comments, Instagram Profiles, Social Scrape, or Artist Socials Scrape to poll for results.

## GET /api/apify/runs/{runId}

Full OpenAPI specification: https://recoupable.dev/docs/spec/social.json

## Authentication

The supplied specification does not declare an OpenAPI security object for this operation. Its declared headers and parameters still apply. Consult the authentication guide and the full specification before calling it.

[Authentication guide](https://recoupable.dev/docs/authentication)

## Operation and referenced schemas

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Recoup API - Social",
    "description": "API documentation for the Recoup platform - an AI agent platform for the music industry",
    "license": {
      "name": "MIT"
    },
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.recoupable.dev"
    }
  ],
  "paths": {
    "/api/apify/runs/{runId}": {
      "get": {
        "description": "Check the status and retrieve results from Apify scraper runs. This endpoint uses the Apify API Client to fetch the current status of a scraper run and its results if available. Use the runId returned from endpoints like Instagram Comments, Instagram Profiles, Social Scrape, or Artist Socials Scrape to poll for results.",
        "parameters": [
          {
            "name": "runId",
            "in": "path",
            "description": "The ID of the Apify run to check status for. This is returned when starting a scrape via Instagram Comments, Instagram Profiles, Social Scrape, or Artist Socials Scrape endpoints.",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "abc123xyz"
          }
        ],
        "responses": {
          "200": {
            "description": "Scraper run status retrieved successfully. Returns status info for in-progress runs, or status info plus data for completed runs.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ApifyScraperInProgressResponse"
                    },
                    {
                      "$ref": "#/components/schemas/ApifyScraperCompletedResponse"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad request - missing required runId parameter",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApifyScraperErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Server error - failed to fetch run status from Apify",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApifyScraperErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ApifyScraperInProgressResponse": {
        "type": "object",
        "required": [
          "status",
          "dataset_id"
        ],
        "description": "Response when the Apify run is still in progress",
        "properties": {
          "status": {
            "type": "string",
            "description": "Current status of the Apify run (e.g., 'RUNNING', 'READY')",
            "example": "RUNNING"
          },
          "dataset_id": {
            "type": "string",
            "description": "ID of the dataset that will contain the results when the run completes",
            "example": "def456uvw",
            "nullable": true
          }
        }
      },
      "ApifyScraperCompletedResponse": {
        "type": "object",
        "required": [
          "status",
          "dataset_id",
          "data"
        ],
        "description": "Response when the Apify run has completed successfully",
        "properties": {
          "status": {
            "type": "string",
            "description": "Final status of the Apify run (typically 'SUCCEEDED')",
            "example": "SUCCEEDED"
          },
          "dataset_id": {
            "type": "string",
            "description": "ID of the dataset containing the results",
            "example": "def456uvw"
          },
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            },
            "description": "Array of dataset items returned by the scraper. The structure of each item varies depending on the scraper type.",
            "example": [
              {
                "id": "123456789",
                "username": "example_user",
                "fullName": "Example User",
                "biography": "This is a sample biography",
                "followersCount": 1000,
                "followsCount": 500,
                "profilePicUrl": "https://example.com/profile.jpg",
                "latestPosts": [
                  {
                    "shortCode": "AbCdEfGhIjK",
                    "type": "Video",
                    "caption": "Example reel caption",
                    "likesCount": 16,
                    "commentsCount": 4,
                    "videoViewCount": 56,
                    "timestamp": "2026-06-30T00:26:41.000Z"
                  }
                ]
              },
              {
                "type": "tweet",
                "id": "1234567890123456789",
                "url": "https://x.com/example_user/status/1234567890123456789",
                "text": "Example tweet text",
                "createdAt": "Wed Jul 01 17:38:08 +0000 2026",
                "likeCount": 7,
                "retweetCount": 2,
                "replyCount": 1,
                "quoteCount": 0,
                "bookmarkCount": 1,
                "viewCount": 258
              },
              {
                "type": "video",
                "id": "aBcDeFgHiJk",
                "title": "Example Short",
                "url": "https://www.youtube.com/watch?v=aBcDeFgHiJk",
                "date": "2026-07-01T17:55:00.000Z",
                "viewCount": 26,
                "likes": 1,
                "commentsCount": 0,
                "duration": "00:00:45",
                "channelUsername": "examplechannel"
              }
            ]
          }
        }
      },
      "ApifyScraperErrorResponse": {
        "type": "object",
        "required": [
          "status",
          "message"
        ],
        "description": "Error response from the Apify scraper results endpoint",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "error"
            ],
            "description": "Status indicating an error occurred"
          },
          "message": {
            "type": "string",
            "description": "Error message describing what went wrong",
            "example": "runId is required"
          }
        }
      }
    }
  }
}
```