# AppKittie Ad Search (`appkittie/appkittie-ads`) Actor

Search and filter mobile app ads through the AppKittie API.

- **URL**: https://apify.com/appkittie/appkittie-ads.md
- **Developed by:** [Appkittie Support](https://apify.com/appkittie) (community)
- **Categories:** Developer tools, Social media
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $250.00 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## AppKittie Ads

Search mobile app ads across Meta and Google ad libraries, or fetch one complete ad record with creative details and advertised-app context.

This Actor is useful for creative research, competitor monitoring, ad inspiration, market validation, and finding which apps are actively buying distribution.

### What Can This Actor Do?

- Search ads by keyword, app, developer, category, country, surface, status, ad source, media type, date range, app downloads, and app revenue.
- Fetch one ad by `adId` for a more complete creative record.
- Return ad copy, media URLs, landing links, activity dates, placement metadata, and advertised-app metrics.
- Use `compact` view for lighter automation-friendly search results.

### Common Use Cases

- Find active ads for high-revenue apps in a category.
- Study hooks, CTAs, headlines, captions, and creative formats from competitors.
- Discover apps scaling through Meta or Google ads.
- Build inspiration feeds for new ad concepts.
- Monitor whether an app is still running a specific creative.

### Input

Choose an `operation`:

- `search` - Calls `GET /api/v1/ads` and returns up to 10 matching ads.
- `details` - Calls `GET /api/v1/ads/{adId}` and returns one complete ad record.

Use `view: "compact"` when you only need identity, status, copy, and app metrics. Use `view: "full"` when you also need media URLs and richer creative fields.

### Example: Search Ads

```json
{
  "operation": "search",
  "search": "meal plan",
  "adSource": "meta",
  "mediaType": "video",
  "status": "active",
  "categories": ["Health & Fitness"],
  "minAppRevenue": 10000,
  "sortBy": "start_date",
  "sortOrder": "desc",
  "limit": 10
}
```

### Example: Get Ad Details

```json
{
  "operation": "details",
  "adId": "meta_1234567890"
}
```

### Output

The Actor writes one typed JSON record to the default key-value store under `OUTPUT`. It does not write dataset rows.

Search output:

```json
{
  "data": [
    {
      "ad_doc_id": "meta_1234567890",
      "ad_source": "meta",
      "type": "video",
      "is_active": true,
      "title": "Start your meal plan today",
      "cta_text": "Install Now",
      "start_date": 1735689600,
      "app_slug": "app-example-id123456789",
      "app_title": "Example App",
      "category": "Health & Fitness",
      "developer": "Example Studio",
      "app_downloads": 85000,
      "app_revenue": 42000
    }
  ],
  "pagination": {
    "nextCursor": 10,
    "totalCount": 152
  }
}
```

Detail output includes the ad plus an `app` summary:

```json
{
  "data": {
    "ad_doc_id": "meta_1234567890",
    "ad_source": "meta",
    "type": "video",
    "src": "https://...",
    "poster": "https://...",
    "body": "Track meals in seconds.",
    "link_url": "https://...",
    "app": {
      "app_slug": "app-example-id123456789",
      "title": "Example App",
      "source": "apple_mobile",
      "downloads": 85000,
      "revenue": 42000
    }
  }
}
```

### Limits and Pagination

Search runs are capped at 10 returned ads. Use `pagination.nextCursor` as the next run's `cursor` to continue paging through results.

Detail operations return one ad per run.

### Notes

- No proxy configuration is required.
- No AppKittie API key is required in Actor input. The Actor uses AppKittie's managed API connection internally.
- Source ad-library identifiers that should not be exposed are redacted from the response.

# Actor input Schema

## `operation` (type: `string`):

Choose which AppKittie ads endpoint to call.

## `adId` (type: `string`):

Required for details. Use an ad document ID returned by ad search or GET /api/v1/ads.

## `search` (type: `string`):

Full-text search across selected ad and app fields.

## `textSearchFields` (type: `array`):

Fields used for full-text search when a search query is provided. Valid values: creative\_text, title, body, caption, description, label, cta\_text, page\_name, developer, app\_title, category.

## `view` (type: `string`):

Use compact for lighter responses without media URLs.

## `appId` (type: `string`):

Optional app filter. Accepts AppKittie slug, numeric App Store ID, Google Play package name, or store URL.

## `adSource` (type: `string`):

Filter by ad library source.

## `mediaType` (type: `string`):

Filter by creative media type.

## `status` (type: `string`):

Filter active or inactive ads.

## `categories` (type: `array`):

App categories to include.

## `excludedCategories` (type: `array`):

App categories to exclude.

## `adLanguages` (type: `array`):

Representative country codes mapped to ad languages, such as US or DE.

## `excludedAdLanguages` (type: `array`):

Representative country codes whose mapped ad languages should be excluded.

## `countries` (type: `array`):

Country or region codes where ads were shown.

## `excludedCountries` (type: `array`):

Country or region codes to exclude.

## `surfaces` (type: `array`):

Publisher surfaces to include.

## `excludedSurfaces` (type: `array`):

Publisher surfaces to exclude.

## `developer` (type: `string`):

Exact app developer name.

## `startedAfter` (type: `integer`):

Unix timestamp in seconds. Returns ads that started after this date.

## `startedBefore` (type: `integer`):

Unix timestamp in seconds. Returns ads that started before this date.

## `endedAfter` (type: `integer`):

Unix timestamp in seconds. Returns ads that ended after this date.

## `endedBefore` (type: `integer`):

Unix timestamp in seconds. Returns ads that ended before this date.

## `minAppDownloads` (type: `integer`):

Minimum estimated monthly downloads for the advertised app.

## `maxAppDownloads` (type: `integer`):

Maximum estimated monthly downloads for the advertised app.

## `minAppRevenue` (type: `integer`):

Minimum estimated monthly revenue for the advertised app.

## `maxAppRevenue` (type: `integer`):

Maximum estimated monthly revenue for the advertised app.

## `limit` (type: `integer`):

Number of ads to return. Actor runs are capped at 10 returned ads.

## `cursor` (type: `integer`):

Pagination offset. Use nextCursor from a previous response.

## `sortBy` (type: `string`):

Field used for sorting.

## `sortOrder` (type: `string`):

Sort direction.

## Actor input object example

```json
{
  "operation": "search",
  "search": "fitness",
  "view": "full",
  "adSource": "all",
  "mediaType": "all",
  "status": "all",
  "limit": 10,
  "sortBy": "start_date",
  "sortOrder": "desc"
}
```

# Actor output Schema

## `result` (type: `string`):

Direct JSON response from the selected AppKittie ads operation. The OUTPUT record is typed by key\_value\_store\_schema.json.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "search": "fitness"
};

// Run the Actor and wait for it to finish
const run = await client.actor("appkittie/appkittie-ads").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "search": "fitness" }

# Run the Actor and wait for it to finish
run = client.actor("appkittie/appkittie-ads").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "search": "fitness"
}' |
apify call appkittie/appkittie-ads --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=appkittie/appkittie-ads",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/OGCVptfeh4hKAMwtG/builds/fiUa9nQV2HVNpFThV/openapi.json