{ "openapi":"3.0.2", "$schema": "https://json-schema.org/draft/2020-12/schema", "info": { "title":"Starscape API Docs", "summary": "The API for Infegy's Starscape platform.", "version":"1.0", "description": "This documentation is specified in an OpenAPI standard, with embedded JSON Schemas. You can access this OpenAPI file programmatically at [https://starscape.infegy.com/api/docs/en/openapi.json](https://starscape.infegy.com/api/docs/en/openapi.json), or save it using the Export button in the upper-right.\n \n# Overview\nThis is the documentation for [Infegy Starscape](https://starscape.infegy.com)'s API. This is the same API that powers our own user interface, so anything possible via the UI can be done programmatically through this API!\n \nThe API is an HTTPS API, primarily speaking JSON. These are extremely popular methods of programatic communication likely supported in your programming language and environment of choice.\n \n## Authentication and Authorization\nThe API uses bearer tokens for authentication. These are specified in the HTTP `Authorization` header with the common format of `Bearer [TOKEN HERE]`. These tokens can be created via the Starscape UI from your [account preferences](https://starscape.infegy.com/me), provisioned by Infegy, or programmatically created using login authorization from the `/create-token` endpoint.\n \nTokens have expiration times, and can be revoked via API or UI. You can view information on your user and token, including expiration and permissions, with a simple GET request to `/me`. The token information is in the `token` member, including `expires_at` and `expires_in_seconds`.\n \nAdditionally, all responses with valid authentication will include two headers assisting in token management:\n* `X-Token-Expires-At` is an ISO8601 date-time indicating when the token provided will expire.\n* `X-Token-Expires-In-Seconds` is a value indicating how long, in seconds, until the provided token will expire.\n \n# Data\nStarscape is predominantly a data and analytics platform. As such, the bulk of functionality in the system is centered around requesting and retreiving data and analysis. The source of this data can be your own, which we store and analyze on your behalf via encrypted private silos known as Datasets. Or you can use our industry-leading social dataset, with hundreds of billions of posts spanning back through 2007, known as the Infegy Social dataset (id `ds_gj4u3F40SLa`)\n \n## Queries\nFor each data endpoint, a query is required. This is a filter, comparable to a WHERE clause in SQL, telling Starscape what data you wish to analyze or retrieve. For example, data within the last 30 days mentioning recipes, or matching any arbitrary combination of filters.\n \nQueries are composed of operator objects. Some can be branching, like `and`, `or`, `not`, which have arrays of sub-values. These can be branching operators, as well, allowing for rich, deep tree-style logic where required. These trees have leaves, which are the value-matching operators, such as `contains`, `>=`, `<`.\n \nThere is no significant restrictions on queries, meaning they can be as simple as a single leaf operator, or a robust as needed for a task.\n \nDetails on the query structure can be found in the `Query` schema on the left.\n \n## Dates and Times\nDates and times in Starscape are always input and output using a subset of [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), as specified in [RFC 3339 section 5.6](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6).\n \nWe extend ISO 8601 in a common way by supporting higher precision beyond seconds. This will only apply to output that has data with such a higher precision. To use this, simply append fractional seconds, making seconds a floating point value. For example, 5 microseconds can be expressed as `0.000005`.\n \n### Relative times and durations\nAdditionally, [ISO 8601 duration formats](https://en.wikipedia.org/wiki/ISO_8601#Durations) are supported, with some extensions expanding capabilities, primarily for relative time use. Our extensions are as follows:\n* *milliseconds* using time designator `I` (capital i)\n* *microseconds* using time designator `U`\n* Prefix with `-` to indicate a backwards relative time. For example, `-P1D` is 1 day ago\n* *Rounding* with `C` (ceiling) or `F` (floor) suffixes. For example, `-P1D` will give us 24 hours ago, whereas `-P1DF` will be midnight yesterday. `P0DC` will be the end of today. Rounding applies to the highest precision unit specified in the period, so if you use days and hours, it will round to hours. This also supports your chosen timezone (see below). \n \n### Timezones\nBy default, Starscape will use the UTC timezone (IANA \"Etc/UTC\") for all dates and times. Queries can specify a time-zone on their top-level object, using the `timezone` member. This is expected to be an IANA timezone identifier. For example, \"America/Chicago\".\n \nWhen used, all time filter values will be assumed to be provided in this timezone, and interpreted accordingly, with any offsets applied from that timezone as a basis. Additionally, aggregations on timestamp fields will do so as if in this timezone. For example, if we specify a timezone and aggregate by day, we will do so from midnight to midnight in your specified timezone. Output labels will be in UTC with your timezone offset applied.\n \n## Localization\nThe API supports translated output, respecting the user's preference first, if set, followed by the \"Accept-Language\" HTTP header. Translation applies to top-level error messages, along with labels for some outputs." }, "servers": [ { "url": "https://starscape.infegy.com/api", "description": "Infegy Starscape Production API" }, { "url": "https://starscape-staging.infegy.com/api", "description": "Infegy Starscape Staging (beta) API" } ], "components": { "securitySchemes": { "api_token": { "type": "http", "scheme": "bearer" } }, "schemas": { "SocialDataset": { "title": "Social Dataset", "description": "id: `ds_gj4u3F40SLa`\n \nThis schema describes the Infegy Social Dataset, contaning approximately 280 billion posts from all over the Web, including many social media platforms. Similar information can be programmatically accessed via the `/query/info` endpoint, which will also include display names and labels for values, which may be localized for your region.\n \nAccess to the dataset is determined by your account plan, along with the historical data accessible. At a maximum, the dataset contains historical data spanning back through 2007, to midnight UTC 2007-01-01.\n \nIf your account has access to this dataset, and no dataset is specified for a query endpoint (such as `/query/agg` or `/query/records`), the social dataset will be used as a default.\n \nProperties below are listed as their ID, usable as a field in query objects, agg / aggregation definitions, or records field selectors. If the display name of the field differs from its ID, the name will be displayed underneath the ID.", "type": "object", "properties": { "published": { "type": "string", "format": "date-time", "minimum": "2007-01-01T00:00:00", "description": "Data type: `timestamp`\n \nTime, with second-level precision, the record was published to the internet, as described in the content when retrieved. If the content has no such date, this will match `fetched`, the time we retrieved the record.", "example": "2024-05-01T12:30:00" }, "source": { "type": "string", "description": "Data type: `keyword`\n \nThe internal identifier of the source of the content, often a unique account on a social media platform, a forum, website, etc. For example, all posts from the same user on a social media platform would have the same `source`.\n \nNOTE: This field does NOT support aggregation.", "example": "1234" }, "body": { "type": "string", "description": "Data type: `text` `Analyzed field`\n \nThe content body of the record, such as the text of a social post. This is a text field, supporting analysis and full-text search.", "example": "Hello world!" }, "link": { "type": "string", "description": "Data type: `keyword`\n \n`NOT INDEXED` This field is not indexed for search, so is not usable in Queries nor Aggregations. It can be returned in Records.\n \nThe URL to the record on the Web. Not guaranteed to exist on every record, though generally will. For example, for a a social post, this will be the URL to the specific post.", "example": "https://www.infegy.com/blog/the-importance-of-social-listening-research" }, "author": { "type": "string", "description": "Data type: `text`\n \nThe author's name, or display name from supported platforms. If there is no such display name, and the platform has a username (the `handle` field), this will contain the username, matching the `handle` field. An example may look like:\n\"Jane Doe (@janedoe)\"\nWhere \"Jane Doe\" is the display name, and \"janedoe\" is the username.\n \nThis field supports full text search, allowing for querying for \"Jane Doe\" as an ordered phrase, for example.", "example": "Infegy (@infegy)" }, "title": { "type": "string", "description": "Data type: `text` `Analyzed field`\n \nThe title of the record, such as the title of a news article, or a video on a social platform. This is a text field, supporting analysis and full-text search.", "example": "My Blog Post Title" }, "geohash": { "title": "Latitude, Longitude", "type": "string", "description": "Name: latitude, longitude\n \nData type: `latitude_longitude`\n \nCoordinates associated with the record, often the location at which the post was made. Note that these are stored as a bounding box with size 39.1km x 19.5km, sub-city-level precision. We can match these coordinates from place names (such as \"Kansas City, MO\") or using explicit coordinates, where provided. They are always stored in these compressed bounding boxes, known as a geohash, so are intentionally not useful for precise location tracking. The geohash format is described [here](https://www.movable-type.co.uk/scripts/geohash.html).", "example": "9yuw" }, "likes": { "type": "integer", "description": "Data type: `integer`\n \nTotal number of \"likes\" (or closest metric, such as upvotes, hearts, thumbs up, etc.) on a social media post. If this field is not relevant for a record, it will always be missing / null.", "example": 1234 }, "shares": { "type": "integer", "description": "Data type: `integer`\n \nTotal number of \"shares\" (or closest metric, such as quotes, reblogs, etc.) on a social media post. If this field is not relevant for a record, it will always be missing / null.", "example": 123 }, "comments": { "type": "integer", "description": "Data type: `integer`\n \nTotal number of \"comments\" (or closest metric, such as replies) on a social media post. If this field is not relevant for a record, it will always be missing / null.", "example": 12 }, "views": { "type": "integer", "description": "Data type: `integer`\n \nTotal number of \"views\" or \"impressions\" of a social media post, video, or image. Not all platforms provide this metric. If this field is not relevant for a record, or the record was collected prior to the metrics availability, or the originating platform does not provide this metric, it will always be missing / null.", "example": 12345 }, "description": { "type": "string", "description": "Data type: `text`\n \nDescriptive info for the record, if available. This can include \"sticker\" text on supported platforms, or descriptions of media, such as AI-generated descriptions of photos. This is a text field, supporting analysis and full-text search.", "example": "Photo of fan blowing ribbons." }, "media_title": { "type": "string", "description": "Data type: `text`\n \nThe title of a song or media used with the record, if available. This is a text field, supporting analysis and full-text search.", "example": "Original sound" }, "total_engagements": { "type": "integer", "description": "Data type: `integer`\n \nTotal number of engagements, as the sum of `likes`, `comments`, and `shares`. If this field is not relevant for a record, it will always be missing / null.", "example": 1369 }, "handle": { "type": "string", "description": "Data type: `keyword`\n \nThe username of the author of the post, if applicable. This will not have an @ or other character prefix or suffix.", "example": "infegy" }, "fetched": { "type": "string", "format": "date-time", "minimum": "2007-01-01T00:00:00", "description": "Data type: `timestamp`\n \nTime, with second-level precision, the record was added to the Social Dataset.", "example": "2024-05-01T12:30:00" }, "is_reply_or_share": { "type": "keyword", "description": "Name: reply or share\n \nData type: `keyword`\n \nThis field will be \"1\" if the post is a reply to another, or \"2\" if it is a share of another. If it is neither, it will be missing / null.", "example": "1", "enum": ["1", "2"] }, "site": { "type": "keyword", "description": "Data type: `keyword`\n \nThis field will be the domain portion of the `link`, such as \"infegy.com\". This can be used to filter to specific websites, platforms, social media networks, and more, such as \"instagram.com\", \"twitter.com\", \"tiktok.com\", etc.", "example": "infegy.com" }, "bio": { "type": "string", "description": "Data type: `text`\n \nThe author's bio or description, or a blog description, sub-reddit description, or other such top-level descriptive information. This is a text field, supporting analysis and full-text search.", "example": "she/her • mom, programmer, artist, writer" }, "links_to": { "type": "array", "items": { "type": "string" }, "description": "Data type: `keywords`\n \n`NOT STORED` This field is not stored, so cannot be retrieved in Records. The links will be present in the text bodies.\n \n`NO AGGREGATION` This field does not support Aggregations.\n \nLinks within the text, in a normalized form for easier search (query inputs will be normalized in the same way to match). For example, if a social post @mentions another user, we will add a \"links_to\" with the URL of that user on the social platform. If a post links to a YouTube video, we'll include that here, and so on.", "example": ["youtube.com/watch?v=dQw4w9WgXcQ", "infegy.com/blog"] }, "rand": { "type": "integer", "description": "Data type: `integer`\n \n`NOT STORED` This field is not stored, so cannot be retrieved in Records.\n \nThis is a random number, with each record always having the same value. Useful for sorting, to retrieve repeatable random samples. The values of this field range from 0 to 2147483647 (2³¹ - 1) inclusive.", "example": 1657682752 }, "country": { "type": "string", "description": "Data type: `keyword`\n \nThe [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code (in lower case) for the record, if identified. This can come from explicit location information, statements like \"I live in Canada\", flag emoji in `bio` fields, locations in `bio` fields, and other such methods.", "example": "fr" }, "channels": { "type": "array", "items": { "type": "string" }, "description": "Data type: `keywords`\n \nOne or more categories or platform names assigned to the record. `site` is preferred for most use-cases of this filter - however, `channels` remains to filter for categories that span multiple domains. Most notably, the `lexisnexis` value will filter on our LexisNexis-sourced Premium News feed, and `news` will filter by our self-categorized social media-based news sources.", "enum": ["lexisnexis", "youtube", "blogs", "microblogs", "twitter", "facebook", "images", "forums", "news", "tumblr", "instagram", "pinterest", "weibo", "reddit", "tiktok", "vk"], "example": ["lexisnexis", "news"] }, "gender": { "type": "string", "description": "Data type: `keyword`\n \nThe inferred gender of the author of the record. This can come from `author` names (in strongly-gender-associated cases), or declarations in the `bio`.\n \nValues are `f` for female, `m` for male, `n` for non-binary. The field will be missing / null if undetermined, unknown, or inapplicable.", "enum": ["f", "m", "n"], "example": "n" }, "influence": { "type": "integer", "minimum": 0, "maximum": 255, "description": "Data type: `integer`\n \nA rating for how influential this source (usually a unique user, or author) is. This score is calculated using frequency of inbound links, mentions, replies, and other social interactions where relevant. As a result, the score works well outside of social platforms, too, as we can follow links to blogs on the web, news sites, etc. to calculate this value. The more frequently the source is linked to, the higher this score will be.\n \nThe score is in a range of 0 (never to almost never linked to) to 255 (extremely high volumes of links), on a logarithmic scale.", "example": 17 }, "source_interests": { "type": "array", "items": { "type": "string" }, "description": "Data type: `keywords`\n \nInterests we've associated with this source (usually a unique user, or author) from their past content. The options are derived from the IAB v2 Content Taxonomy's first two tiers.", "enum": ["Travel|Travel Type","Travel|Travel Locations","Technology & Computing|Computing","Personal Finance|Insurance","Events and Attractions|Personal Celebrations & Life Events","Education|Primary Education","Careers|Career Planning","Careers|Career Advice","Careers|Apprenticeships","Business and Finance|Business","Automotive|Auto Insurance","Automotive|Auto Type","Sports|Extreme Sports","Television|Soap Opera TV","Style & Fashion|Beauty","Sports|Lacrosse","Sports|Fantasy Sports","Movies|World Movies","Real Estate|Developmental Sites","Music and Audio|Talk Radio","Music and Audio|Rock Music","Music and Audio|College Radio","Hobbies & Interests|Collecting","Hobbies & Interests|Arts and Crafts","Events and Attractions|Fashion Events","Education|Homeschooling","Education|Adult Education","Careers|Remote Working","Business and Finance|Industries","Events and Attractions|Cinemas and Events","Religion & Spirituality","Real Estate|Land and Farms","Real Estate|Industrial Property","Real Estate|Houses","Real Estate","Pop Culture|Celebrity Relationships","Pets","Pop Culture","Pets|Fish and Aquariums","Pets|Birds","Pets|Pet Supplies","Medical Health|Diseases and Conditions","Personal Finance","News and Politics|Politics","News and Politics|Crime","Automotive|Auto Body Styles","News and Politics","Music and Audio|R&B/Soul/Funk","Style & Fashion|Personal Care","Music and Audio|Blues","Music and Audio|Reggae","Music and Audio|Alternative Music","Music and Audio|Oldies/Adult Standards","Business and Finance|Economy","Music and Audio|Religious (Music and Audio","Music and Audio|World/International Music","Careers|Job Search","Movies|Drama Movies","Sports|Ice Hockey","Personal Finance|Personal Investing","Family and Relationships|Parenting","Music and Audio|Classical Music","Music and Audio|Classic Hits","Style & Fashion|Men's Fashion","Movies|Crime and Mystery Movies","Music and Audio|Gospel Music","Books and Literature|Fiction","Movies|Comedy Movies","Television|Reality TV","Music and Audio|Sports Radio","Movies|Animation Movies","Events and Attractions|Malls & Shopping Centers","Real Estate|Vacation Properties","Home & Garden","Books and Literature","Automotive|Auto Safety","Real Estate|Hotel Properties","Movies|Action and Adventure Movies","Personal Finance|Personal Debt","Medical Health|Surgery","Personal Finance|Retirement Planning","Home & Garden|Landscaping","Hobbies & Interests|Model Toys","Music and Audio|Songwriters/Folk","Hobbies & Interests|Games and Puzzles","Automotive|Auto Parts","Education|Secondary Education","Real Estate|Real Estate Buying and Selling","Events and Attractions|Museums & Galleries","Hobbies & Interests|Content Production","Events and Attractions|Outdoor Activities","Movies|Horror Movies","Sports|Water Polo","Healthy Living|Senior Health","Hobbies & Interests|Paranormal Phenomena","Sports|Martial Arts","Personal Finance|Financial Assistance","Pets|Cats","Sports|Beach Volleyball","Hobbies & Interests|Musical Instruments","Food & Drink|Dining Out","Pop Culture|Celebrity Pregnancy","Food & Drink|Alcoholic Beverages","Hobbies & Interests","Personal Finance|Home Utilities","Healthy Living|Wellness","Movies|Fantasy Movies","Video Gaming|Video Game Genres","Family and Relationships|Eldercare","Pets|Dogs","Shopping","Sports|Badminton","Science|Space and Astronomy","Home & Garden|Home Improvement","Home & Garden|Home Appliances","Events and Attractions|Amusement and Theme Parks","News and Politics|Weather","Family and Relationships|Marriage and Civil Unions","Television|Music TV","Medical Health|Pharmaceutical Drugs","Pop Culture|Celebrity Families","Home & Garden|Interior Decorating","Pop Culture|Celebrity Deaths","Business and Finance","Movies","Pets|Pet Adoptions","Events and Attractions|Musicals","Hobbies & Interests|Sci-fi and Fantasy","Home & Garden|Gardening","Automotive|Road-Side Assistance","Events and Attractions|Sporting Events","Automotive","Sports|Rowing","Healthy Living|Weight Loss","Music and Audio|Jazz","Religion & Spirituality|Atheism","Fine Art|Design","Events and Attractions|Bars & Restaurants","Sports|Gymnastics","Sports|Walking","Pop Culture|Humor and Satire","Science|Physics","Style & Fashion|Street Style","Sports|Cheerleading","Food & Drink|Food Movements","Movies|Romance Movies","Hobbies & Interests|Workshops and Classes","Music and Audio|Soundtracks, TV and Showtunes","Personal Finance|Personal Taxes","Real Estate|Office Property","Movies|Indie and Arthouse Movies","Shopping|Flower Shopping","Education|Educational Assessment","Music and Audio|Hip Hop Music","Sports|College Sports","Books and Literature|Biographies","Hobbies & Interests|Birdwatching","Style & Fashion|Women's Fashion","Movies|Science Fiction Movies","Home & Garden|Indoor Environmental Quality","Religion & Spirituality|Judaism","Religion & Spirituality|Christianity","Technology & Computing|Virtual Reality","Fine Art|Dance","Movies|Family and Children Movies","Sports|Olympic Sports","Automotive|Motorcycles","Events and Attractions|Concerts & Music Events","Automotive|Auto Technology","Technology & Computing|Augmented Reality","Careers","Pets|Veterinary Medicine","Events and Attractions|National & Civic Holidays","Automotive|Car Culture","Food & Drink","Pop Culture|Celebrity Scandal","Events and Attractions|Zoos & Aquariums","Hobbies & Interests|Beekeeping","Sports|Fishing Sports","Sports|Basketball","Food & Drink|Non-Alcoholic Beverages","Home & Garden|Remodeling & Construction","Medical Health|Vaccines","Education|Online Education","Pop Culture|Celebrity Style","Music and Audio","Events and Attractions|Historic Site and Landmark Tours","Sports|Track and Field","Education|College Education","Events and Attractions|Comedy Events","Music and Audio|Dance and Electronic Music","Events and Attractions|Parks & Nature","Fine Art|Digital Arts","Events and Attractions|Awards Shows","Food & Drink|Food Allergies","Sports|Soccer","Video Gaming","Education","Family and Relationships|Dating","Events and Attractions|Religious Events","Religion & Spirituality|Astrology","Events and Attractions|Business Expos & Conferences","Education|Special Education","Family and Relationships","Healthy Living|Men's Health","Family and Relationships|Bereavement","Fine Art|Modern Art","Hobbies & Interests|Genealogy and Ancestry","Events and Attractions|Nightclubs","Fine Art","Family and Relationships|Single Life","Sports|Australian Rules Football","Medical Health|Medical Tests","Events and Attractions","Food & Drink|Vegan Diets","Fine Art|Theater","Religion & Spirituality|Agnosticism","News and Politics|Disasters","Food & Drink|Cooking","Food & Drink|Healthy Cooking and Eating","Food & Drink|Desserts and Baking","Personal Finance|Consumer Banking","Healthy Living","Medical Health","Healthy Living|Children's Health","Technology & Computing|Consumer Electronics","Events and Attractions|Party Supplies and Decorations","Food & Drink|World Cuisines","Sports|Wrestling","Religion & Spirituality|Buddhism","Religion & Spirituality|Islam","Real Estate|Real Estate Renting and Leasing","Science|Biological Sciences","Science|Chemistry","Automotive|Auto Shows","Science|Environment","Music and Audio|Contemporary Hits/Pop/Top 40","Science|Genetics","Religion & Spirituality|Spirituality","Science|Geography","Science|Geology","Shopping|Household Supplies","Shopping|Sales and Promotions","Education|Private School","Shopping|Children's Games and Toys","Sports","Sports|Cycling","Sports|Diving","Hobbies & Interests|Cigars","Sports|Equine Sports","Sports|Field Hockey","Hobbies & Interests|Antiquing and Antiques","Sports|Sailing","Sports|Softball","Sports|Tennis","Style & Fashion","Sports|Poker and Professional Gambling","Fine Art|Opera","Style & Fashion|Body Art","Style & Fashion|Fashion Trends","Technology & Computing","Technology & Computing|Artificial Intelligence","Careers|Vocational Training","Food & Drink|Vegetarian Diets","Technology & Computing|Robotics","Real Estate|Retail Property","Sports|Rodeo","Television","Events and Attractions|Casinos & Gambling","Style & Fashion|High Fashion","Television|Comedy TV","Television|Drama TV","News and Politics|Law","Automotive|Auto Repair","Television|Science Fiction TV","Music and Audio|Country Music","Video Gaming|Console Games","Video Gaming|eSports","Books and Literature|Poetry","Video Gaming|Mobile Games","Video Gaming|PC Games","Sports|Skiing","Automotive|Scooters","Books and Literature|Travel Books","Education|Early Childhood Education","Automotive|Auto Rentals","Events and Attractions|Fan Conventions","Science","Food & Drink|Barbecues and Grilling","Sports|Hunting and Shooting","Hobbies & Interests|Magic and Illusion","Healthy Living|Fitness and Exercise","Home & Garden|Smart Home","Automotive|Auto Buying and Selling","Sports|Swimming","Medical Health|Cosmetic Medical Services","Movies|Documentary Movies","News and Politics|International News","Personal Finance|Financial Planning","Pets|Reptiles","Events and Attractions|Theater Venues and Events","Religion & Spirituality|Sikhism","Shopping|Grocery Shopping","Sports|Bodybuilding","Real Estate|Apartments","Family and Relationships|Divorce","Sports|Sports Equipment","Sports|Golf","Shopping|Gifts and Greetings Cards","Books and Literature|Comics and Graphic Novels","Television|Animation TV","Books and Literature|Cookbooks","Events and Attractions|Political Event","Sports|Disabled Sports","Sports|Auto Racing","Fine Art|Costume","Music and Audio|Inspirational/New Age Music","Education|Language Learning","Fine Art|Fine Art Photography","Books and Literature|Young Adult Literature","Travel","Shopping|Coupons and Discounts","Shopping|Lotteries and Scratchcards","Sports|American Football","Sports|Boxing","Books and Literature|Art and Photography Books","Television|Sports TV","Sports|Cricket","Sports|Darts","Sports|Figure Skating","Sports|Inline Skating","Television|Holiday TV","Sports|Rugby","Sports|Snooker/Pool/Billiards","Sports|Table Tennis","Sports|Weightlifting","Sports|Baseball","Healthy Living|Nutrition","Sports|Volleyball","Television|Factual TV","Sports|Squash","Hobbies & Interests|Radio Control","Religion & Spirituality|Hinduism","Music and Audio|Comedy (Music and Audio","Sports|Bowling"], "example": ["Technology & Computing|Internet", "Technology & Computing", "News and Politics|Elections", "News and Politics", "Pop Culture|Humor and Satire", "Pop Culture"] }, "source_age": { "type": "integer", "minimum": 13, "maximum": 122, "description": "Data type: `integer`\n \nAn inferred age for the source (usually a unique user, or author), as determined from their content, if possible and relevant.", "example": 35 }, "followers": { "type": "integer", "description": "Data type: `integer`\n \nThe last known value for the number of followers (or similar metric, such as fans, or subscribers) for this user. If this field is not relevant for a record, it will always be missing / null.", "example": 1200000 }, "following": { "type": "integer", "description": "Data type: `integer`\n \nThe last known value for the number of other users this user is following (or similar metric, such as their total subscriptions) for this user. If this field is not relevant for a record, it will always be missing / null.", "example": 120 }, "language": { "type": "string", "description": "Data type: `keyword`\n \nThe detected language the content is written in. We can detect 156 languages, covering the vast majority of written language on the Web. The values are lower-case [ISO 639-2](https://en.wikipedia.org/wiki/List_of_ISO_639-2_codes) codes.", "example": "en" }, "sentiment": { "type": "string", "description": "Data type: `keyword`\n \nDetected sentiment for the record, as `p` (positive), `n` (negative), or `0` (neutral). If we did not analyze the record, or analsis was unable to determine sentiment, this field will be missing / null.", "example": "p" }, "themes": { "type": "array", "items": { "type": "string" }, "description": "Data type: `keywords`\n \nDetected high-level themes mentioned in the record. If we did not analyze the record, or analsis was unable to detect any themes, this field will be missing / null.", "enum": ["availability", "convenience", "expectation", "intent", "place", "promotion", "quality", "risk", "service", "service|satisfaction", "risk|injury", "quality|craftmanship", "convenience|location", "service|wait times", "place|restrooms", "quality|temperature", "place|access", "place|ambiance", "availability|stock", "quality|appearance", "promotion|discounts", "availability|selection", "promotion|ads", "convenience|delivery", "risk|criminal", "service|knowledge", "service|speed", "expectation|fit", "service|friendliness", "risk|illness", "promotion|cost", "place|cleanliness", "quality|taste", "expectation|experience", "intent|loyalty", "intent|churn", "place|comfort", "quality|durability", "convenience|transaction", "intent|purchase", "service|leadership"], "example": ["service|satisfaction", "service", "risk|injury", "risk"] }, "emotions": { "type": "array", "items": { "type": "string" }, "description": "Data type: `keywords`\n \nDetected emotions expressed in the record. These options are derived from the 8 core emotions in Plutchik's Wheel, with the additions of `love` and `hate`. If we did not analyze the record, or analsis was unable to detect any emotions, this field will be missing / null.", "enum": ["love", "anticipation", "anger", "disgust", "sadness", "hate", "surprise", "fear", "trust", "joy"], "example": ["love", "joy", "surprise"] }, "entities": { "type": "array", "items": { "type": "string" }, "description": "Data type: `keywords`\n \nKnown entities seen in the record, as detected by our analysis. These entities cover more than 1.8 million people, companies, brands, sports teams, and media, all derived from Wikipedia. They are filtered to and expressed using small unique identifiers. The associated name will be returned with Records in the `value_labels` object, and can be found using the `/query/suggest` endpoint. If we did not analyze the record, or analsis was unable to detect any entities, this field will be missing / null.", "example": ["0N5d", "Od"] }, "taxonomies": { "type": "array", "items": { "type": "string" }, "description": "**Name**: Content subject\n \nData type: `keywords`\n \nSubject matter mentioned within the record. These are derived from the IAB v2 Content Taxonomy, including more than 500 possible categories. The taxonomy is 4 tiers. If we tag a lower tier, the upper tiers will always be included as well. For example, if `Sports|Cycling` is detected, we'll also include `Sports`. If we did not analyze the record, or analsis was unable to detect a subject, this field will be missing / null.", "enum": ["Sports","Technology & Computing","Business and Finance","Hobbies & Interests","News and Politics","Events and Attractions","Music and Audio","Pop Culture","Medical Health","Style & Fashion","Video Gaming","Food & Drink","Religion & Spirituality","Movies","Automotive","Personal Finance","Family and Relationships","Fine Art","Travel","Television","Science","Home & Garden","Healthy Living","Books and Literature","Pets","News and Politics|Politics","Real Estate","Shopping","Style & Fashion|Men's Fashion","Style & Fashion|Women's Fashion","Careers","Pop Culture|Humor and Satire","Education","News and Politics|Crime","News and Politics|Politics|Elections","Pop Culture|Celebrity Deaths","Medical Health|Diseases and Conditions|Mental Health","Sports|Soccer","News and Politics|Politics|Political Issues","Technology & Computing|Computing|Internet|Social Networking","Fine Art|Design","Hobbies & Interests|Genealogy and Ancestry","Food & Drink|Desserts and Baking","News and Politics|Disasters","Religion & Spirituality|Atheism","Religion & Spirituality|Islam","Pop Culture|Celebrity Relationships","Video Gaming|PC Games","Pets|Dogs","Religion & Spirituality|Astrology","Family and Relationships|Dating","Technology & Computing|Computing|Internet","Religion & Spirituality|Christianity","Technology & Computing|Computing|Internet|Web Development","Family and Relationships|Parenting|Internet Safety","Medical Health|Medical Tests","Religion & Spirituality|Spirituality","Sports|American Football","Hobbies & Interests|Arts and Crafts|Photography","Video Gaming|Video Game Genres|Action Video Games","Sports|Sports Equipment","Family and Relationships|Single Life","Events and Attractions|Personal Celebrations & Life Events","Events and Attractions|Concerts & Music Events","Technology & Computing|Artificial Intelligence","Music and Audio|Hip Hop Music","Science|Chemistry","Hobbies & Interests|Games and Puzzles","Events and Attractions|Personal Celebrations & Life Events|Birthday","Business and Finance|Business","Sports|Basketball","Technology & Computing|Computing","Personal Finance|Personal Investing|Stocks and Bonds","Shopping|Sales and Promotions","Movies|Romance Movies","Real Estate|Real Estate Buying and Selling","Movies|Crime and Mystery Movies","Style & Fashion|Fashion Trends","Hobbies & Interests|Collecting","Music and Audio|Rock Music","Technology & Computing|Computing|Computer Software and Applications|Digital Audio","Automotive|Auto Safety","Movies|Horror Movies","Business and Finance|Business|Marketing and Advertising","News and Politics|Law","Home & Garden|Gardening","Hobbies & Interests|Content Production|Video Production","Video Gaming|Video Game Genres|Adventure Video Games","Music and Audio|R&B/Soul/Funk","Medical Health|Diseases and Conditions|Heart and Cardiovascular Diseases","Style & Fashion|Women's Fashion|Women's Accessories","Events and Attractions|Sporting Events","Fine Art|Theater","Food & Drink|Cooking","Technology & Computing|Consumer Electronics|Smartphones","Music and Audio|Songwriters/Folk","Hobbies & Interests|Paranormal Phenomena","Sports|Baseball","News and Politics|Politics|War and Conflicts","Family and Relationships|Marriage and Civil Unions","Medical Health|Diseases and Conditions|Diabetes","Technology & Computing|Computing|Internet|Web Hosting","Music and Audio|Classic Hits","Music and Audio|Talk Radio|News/Talk Radio","Business and Finance|Economy|Currencies","Personal Finance|Home Utilities|Phone Services","Hobbies & Interests|Content Production","Books and Literature|Fiction","Events and Attractions|Nightclubs","Careers|Job Search|Resume Writing and Advice","Music and Audio|Contemporary Hits/Pop/Top 40","Food & Drink|Vegetarian Diets","Food & Drink|Dining Out","Technology & Computing|Computing|Internet|Email","Movies|Fantasy Movies","Video Gaming|Video Game Genres|Sports Video Games","Movies|Comedy Movies","Hobbies & Interests|Content Production|Freelance Writing","Science|Space and Astronomy","Travel|Travel Type","Home & Garden|Home Improvement","Video Gaming|Video Game Genres|Puzzle Video Games","Sports|Hunting and Shooting","Fine Art|Modern Art","Automotive|Auto Type|Performance Cars","Personal Finance|Financial Assistance|Government Support and Welfare","Events and Attractions|Bars & Restaurants","Travel|Travel Type|Road Trips","Video Gaming|Video Game Genres|Music and Party Video Games","News and Politics|Weather","Home & Garden|Interior Decorating","Business and Finance|Business|Business Administration","Video Gaming|Video Game Genres|Role-Playing Video Games","Personal Finance|Consumer Banking","Technology & Computing|Computing|Internet|Internet of Things","Business and Finance|Business|Large Business","Sports|Olympic Sports|Winter Olympic Sports","Video Gaming|Mobile Games","Food & Drink|Vegan Diets","Science|Physics","Sports|Walking","Music and Audio|Gospel Music","Personal Finance|Personal Investing","Television|Drama TV","Pop Culture|Celebrity Families","Pets|Cats","Education|Online Education","Fine Art|Dance","Technology & Computing|Virtual Reality","Video Gaming|Video Game Genres|Action-Adventure Video Games","Hobbies & Interests|Workshops and Classes","Video Gaming|Video Game Genres|Strategy Video Games","Style & Fashion|Beauty","Healthy Living|Fitness and Exercise","Technology & Computing|Computing|Computer Networking","Events and Attractions|Personal Celebrations & Life Events|Anniversary","Television|Holiday TV","Food & Drink|World Cuisines","Technology & Computing|Computing|Computer Software and Applications|Graphics Software","Books and Literature|Biographies","Home & Garden|Remodeling & Construction","Technology & Computing|Consumer Electronics","Travel|Travel Type|Camping","Music and Audio|Dance and Electronic Music","Hobbies & Interests|Arts and Crafts|Drawing and Sketching","Movies|Science Fiction Movies","Careers|Job Search|Job Fairs","Video Gaming|eSports","Medical Health|Diseases and Conditions|Eye and Vision Conditions","Food & Drink|Non-Alcoholic Beverages","Automotive|Auto Type","Home & Garden|Home Appliances","Hobbies & Interests|Arts and Crafts","Careers|Job Search","Healthy Living|Men's Health","Business and Finance|Industries|Legal Services Industry","Music and Audio|Classical Music","Events and Attractions|Awards Shows","Business and Finance|Business|Business I.T.","Events and Attractions|Fan Conventions","Events and Attractions|Religious Events","Pets|Pet Supplies","News and Politics|International News","Style & Fashion|Body Art","Events and Attractions|Musicals","Events and Attractions|Outdoor Activities","Automotive|Auto Technology","Technology & Computing|Computing|Information and Network Security","Television|Science Fiction TV","Automotive|Auto Type|Luxury Cars","Events and Attractions|Business Expos & Conferences","Technology & Computing|Computing|Computer Software and Applications|Computer Animation","Events and Attractions|Amusement and Theme Parks","Video Gaming|Video Game Genres|Educational Video Games","Business and Finance|Industries|Food Industry","Healthy Living|Children's Health","Personal Finance|Personal Investing|Options","Style & Fashion|Personal Care","Events and Attractions|Political Event","Medical Health|Diseases and Conditions|Injuries","Sports|College Sports|College Basketball","Pets|Veterinary Medicine","Sports|Olympic Sports|Summer Olympic Sports","Religion & Spirituality|Buddhism","Fine Art|Opera","Sports|College Sports|College Football","Events and Attractions|National & Civic Holidays","Personal Finance|Home Utilities|Gas and Electric","Music and Audio|Rock Music|Hard Rock","Pets|Birds","Business and Finance|Industries|Automotive Industry","Books and Literature|Young Adult Literature","Style & Fashion|Personal Care|Bath and Shower","Medical Health|Diseases and Conditions|Ear, Nose and Throat Conditions","Books and Literature|Travel Books","Food & Drink|Food Movements","Television|Animation TV","Business and Finance|Industries|Civil Engineering Industry","Food & Drink|Healthy Cooking and Eating","Science|Geography","Television|Music TV","Business and Finance|Economy","Technology & Computing|Computing|Computer Software and Applications|Video Software","Science|Environment","Home & Garden|Landscaping","Healthy Living|Nutrition","Shopping|Children's Games and Toys","Hobbies & Interests|Games and Puzzles|Roleplaying Games","Medical Health|Vaccines","Real Estate|Vacation Properties","Travel|Travel Locations|Asia Travel","Medical Health|Diseases and Conditions|Sleep Disorders","Medical Health|Diseases and Conditions|Sexual Health","Music and Audio|Religious (Music and Audio)","Sports|Boxing","Television|Sports TV","Sports|Badminton","Science|Biological Sciences","Sports|Fishing Sports","Business and Finance|Business|Business Accounting & Finance","Hobbies & Interests|Arts and Crafts|Painting","Business and Finance|Industries|Apparel Industry","Family and Relationships|Bereavement","Family and Relationships|Parenting","Hobbies & Interests|Musical Instruments","Sports|Martial Arts","Automotive|Auto Body Styles|Off-Road Vehicles","Travel|Travel Type|Cruises","Medical Health|Diseases and Conditions|Cold and Flu","Religion & Spirituality|Hinduism","Science|Genetics","Technology & Computing|Computing|Computer Peripherals","Movies|Drama Movies","Fine Art|Fine Art Photography","Sports|Equine Sports","Medical Health|Diseases and Conditions|Cancer","Hobbies & Interests|Games and Puzzles|Board Games and Puzzles","Sports|Softball","Travel|Travel Type|Adventure Travel","Music and Audio|Comedy (Music and Audio)","Movies|Family and Children Movies","Music and Audio|Blues","Pop Culture|Celebrity Scandal","Business and Finance|Industries|Agriculture","Automotive|Auto Body Styles|Commercial Trucks","Television|Comedy TV","Music and Audio|Oldies/Adult Standards","Business and Finance|Business|Business Banking & Finance|Private Equity","Business and Finance|Industries|Publishing Industry","Food & Drink|Alcoholic Beverages","Sports|Figure Skating","Sports|Swimming","Sports|Gymnastics","Music and Audio|Country Music","Sports|Auto Racing|Motorcycle Sports","Medical Health|Diseases and Conditions|Brain and Nervous System Disorders","Business and Finance|Industries|Manufacturing Industry","Hobbies & Interests|Games and Puzzles|Card Games","Shopping|Grocery Shopping","Religion & Spirituality|Sikhism","Business and Finance|Business|Sales","Events and Attractions|Casinos & Gambling","Events and Attractions|Personal Celebrations & Life Events|Funeral","Technology & Computing|Computing|Internet|Cloud Computing","Video Gaming|Video Game Genres|Casual Games","Business and Finance|Industries|Media Industry","Sports|Australian Rules Football","Sports|Equine Sports|Horse Racing","Family and Relationships|Parenting|Daycare and Pre-School","Sports|Extreme Sports","Real Estate|Real Estate Renting and Leasing","Personal Finance|Personal Debt","Technology & Computing|Consumer Electronics|Tablets and E-readers","Movies|Animation Movies","Television|Reality TV","Sports|Track and Field","Video Gaming|Video Game Genres|MMOs","Healthy Living|Fitness and Exercise|Running and Jogging","Sports|Sailing","Family and Relationships|Parenting|Special Needs Kids","Real Estate|Houses","Events and Attractions|Cinemas and Events","Sports|Darts","Travel|Travel Type|Rail Travel","Business and Finance|Industries|Logistics and Transportation Industry","Medical Health|Diseases and Conditions","Video Gaming|Video Game Genres|Simulation Video Games","Music and Audio|World/International Music","Style & Fashion|Beauty|Perfume and Fragrance","Business and Finance|Industries|Defense Industry","Business and Finance|Industries|Non-Profit Organizations","Sports|Cheerleading","Hobbies & Interests|Arts and Crafts|Needlework","Family and Relationships|Divorce","Movies|Indie and Arthouse Movies","Business and Finance|Industries|Real Estate Industry","Family and Relationships|Parenting|Adoption and Fostering","Science|Geology","Technology & Computing|Consumer Electronics|Cameras and Camcorders","Technology & Computing|Computing|Programming Languages","Books and Literature|Art and Photography Books","Travel|Travel Locations","Hobbies & Interests|Model Toys","Sports|Cricket","Sports|Rugby","Sports|Auto Racing","Fine Art|Digital Arts","Technology & Computing|Computing|Computer Software and Applications|Operating Systems","Sports|Ice Hockey","Technology & Computing|Computing|Computer Software and Applications|Shareware and Freeware","Medical Health|Diseases and Conditions|Injuries|First Aid","Music and Audio|Rock Music|Soft Rock","Food & Drink|Barbecues and Grilling","Movies|Action and Adventure Movies","Technology & Computing|Computing|Internet|Web Design and HTML","Business and Finance|Industries|Biotech and Biomedical Industry","Automotive|Auto Type|Electric Cars","Sports|Tennis","Books and Literature|Poetry","Music and Audio|Rock Music|Alternative Rock","Personal Finance|Insurance","Technology & Computing|Consumer Electronics|Wearable Technology","Business and Finance|Economy|Financial Regulation","Sports|Poker and Professional Gambling","Business and Finance|Industries|Construction Industry","Automotive|Motorcycles","Technology & Computing|Augmented Reality","Sports|Disabled Sports","Books and Literature|Comics and Graphic Novels","Medical Health|Diseases and Conditions|Infectious Diseases","Shopping|Coupons and Discounts","Healthy Living|Weight Loss","Religion & Spirituality|Judaism","Sports|Volleyball","Video Gaming|Console Games","Music and Audio|Reggae","Technology & Computing|Computing|Computer Software and Applications|Browsers","Medical Health|Surgery","Shopping|Flower Shopping","Sports|Bodybuilding","Sports|Cycling","Events and Attractions|Personal Celebrations & Life Events|Wedding","Careers|Vocational Training","Hobbies & Interests|Magic and Illusion","Technology & Computing|Robotics","Hobbies & Interests|Arts and Crafts|Woodworking","Music and Audio|Jazz","Medical Health|Pharmaceutical Drugs","Technology & Computing|Computing|Computer Software and Applications","Music and Audio|Inspirational/New Age Music","Sports|Wrestling","Music and Audio|Talk Radio|Public Radio","Careers|Career Advice","Sports|College Sports","Events and Attractions|Parks & Nature","Fine Art|Costume","Business and Finance|Business|Consumer Issues","Real Estate|Industrial Property","Business and Finance|Industries","Automotive|Auto Parts","Business and Finance|Business|Green Solutions","Events and Attractions|Fashion Events","Religion & Spirituality|Agnosticism","Events and Attractions|Party Supplies and Decorations","Style & Fashion|Beauty|Skin Care","Hobbies & Interests|Content Production|Audio Production","Technology & Computing|Computing|Desktops","Music and Audio|Soundtracks, TV and Showtunes","Healthy Living|Wellness|Alternative Medicine","Medical Health|Diseases and Conditions|Reproductive Health|Birth Control","Shopping|Household Supplies","Medical Health|Diseases and Conditions|Lung and Respiratory Health","Business and Finance|Industries|Technology Industry","Business and Finance|Business|Business Banking & Finance|Mergers and Acquisitions","Home & Garden|Indoor Environmental Quality","Pets|Fish and Aquariums","Personal Finance|Personal Debt|Credit Cards","Pop Culture|Celebrity Pregnancy","Events and Attractions|Theater Venues and Events","Automotive|Auto Type|Concept Cars","Travel|Travel Type|Hotels and Motels","Automotive|Auto Type|Green Vehicles","Education|College Education","Personal Finance|Financial Planning","Personal Finance|Insurance|Life Insurance","Real Estate|Retail Property","Style & Fashion|Beauty|Makeup and Accessories","Style & Fashion|Personal Care|Deodorant and Antiperspirant","Automotive|Auto Technology|Auto Safety Technologies","Personal Finance|Personal Taxes","Technology & Computing|Computing|Computer Software and Applications|3-D Graphics","Automotive|Scooters","Video Gaming|Video Game Genres","Sports|Diving","Sports|Squash","Automotive|Auto Body Styles|Convertible","Style & Fashion|Street Style","Education|Adult Education","Technology & Computing|Computing|Computer Software and Applications|Databases","Sports|Extreme Sports|Snowboarding","Sports|Golf","Style & Fashion|Personal Care|Oral care","Education|Homeschooling","Healthy Living|Senior Health","Video Gaming|Video Game Genres|Exercise and Fitness Video Games","Healthy Living|Wellness|Physical Therapy","Real Estate|Land and Farms","Business and Finance|Business|Business Banking & Finance|Business Loans","Business and Finance|Business|Business Banking & Finance|Angel Investment","Automotive|Auto Body Styles|Hatchback","Education|College Education|Postgraduate Education|Professional School","Automotive|Auto Body Styles|Van","Business and Finance|Business|Consumer Issues|Recalls","Automotive|Auto Body Styles|SUV","Technology & Computing|Computing|Internet|Search","Sports|College Sports|College Baseball","Events and Attractions|Malls & Shopping Centers","Hobbies & Interests|Sci-fi and Fantasy","Healthy Living|Wellness|Alternative Medicine|Herbs and Supplements","Automotive|Auto Repair","Style & Fashion|Women's Fashion|Women's Accessories|Women's Glasses","Automotive|Car Culture","Automotive|Auto Body Styles|Coupe","Sports|Water Polo","Hobbies & Interests|Birdwatching","Movies|Documentary Movies","Business and Finance|Industries|Mechanical and Industrial Engineering Industry","Technology & Computing|Computing|Laptops","Personal Finance|Home Utilities|Internet Service Providers","Medical Health|Diseases and Conditions|Digestive Disorders","Events and Attractions|Historic Site and Landmark Tours","Travel|Travel Type|Air Travel","Education|Secondary Education","Style & Fashion|High Fashion","Personal Finance|Retirement Planning","Medical Health|Diseases and Conditions|Substance Abuse","Hobbies & Interests|Beekeeping","Medical Health|Diseases and Conditions|Skin and Dermatology","Business and Finance|Industries|Power and Energy Industry","Automotive|Auto Body Styles|Sedan","Sports|Extreme Sports|Surfing and Bodyboarding","Real Estate|Developmental Sites","Sports|Skiing","Sports|Table Tennis","Events and Attractions|Zoos & Aquariums","Business and Finance|Economy|Job Market","Travel|Travel Locations|Europe Travel","Business and Finance|Industries|Information Services Industry","Education|Language Learning","Sports|Snooker/Pool/Billiards","Music and Audio|Talk Radio","Education|Educational Assessment|Standardized Testing","Automotive|Auto Body Styles","Automotive|Auto Body Styles|Pickup Trucks","Medical Health|Diseases and Conditions|Blood Disorders","Technology & Computing|Computing|Computer Software and Applications|Photo Editing Software","Television|Factual TV","Business and Finance|Business|Business Banking & Finance|Venture Capital","Business and Finance|Business|Executive Leadership & Management","Sports|Lacrosse","Business and Finance|Industries|Metals Industry","Automotive|Auto Body Styles|Minivan","Medical Health|Diseases and Conditions|Bone and Joint Conditions","Sports|Extreme Sports|Skateboarding","Travel|Travel Locations|Australia and Oceania Travel","Business and Finance|Industries|Healthcare Industry","Business and Finance|Business|Startups","Pets|Reptiles","Business and Finance|Industries|Pharmaceutical Industry","Personal Finance|Home Utilities|Water Services","Hobbies & Interests|Arts and Crafts|Jewelry Making","Sports|Weightlifting","Automotive|Auto Technology|Auto Infotainment Technologies","Books and Literature|Cookbooks","Technology & Computing|Computing|Internet|IT and Internet Support","Travel|Travel Locations|South America Travel","Personal Finance|Personal Investing|Mutual Funds","Travel|Travel Type|Bed & Breakfasts","Events and Attractions|Comedy Events","Personal Finance|Financial Assistance|Student Financial Aid","Business and Finance|Industries|Telecommunications Industry","Travel|Travel Type|Spas","Home & Garden|Smart Home","Travel|Travel Locations|Africa Travel","Events and Attractions|Museums & Galleries","Hobbies & Interests|Radio Control","Medical Health|Diseases and Conditions|Reproductive Health|Infertility","Medical Health|Diseases and Conditions|Allergies","Sports|Rodeo","Automotive|Auto Rentals","Music and Audio|College Radio","Personal Finance|Personal Debt|Home Financing","Travel|Travel Locations|North America Travel","Events and Attractions|Personal Celebrations & Life Events|Bachelorette Party","Automotive|Auto Type|Classic Cars","Sports|Rowing","Careers|Remote Working","Medical Health|Diseases and Conditions|Foot Health","Events and Attractions|Personal Celebrations & Life Events|Graduation","Automotive|Auto Body Styles|Station Wagon","Hobbies & Interests|Collecting|Comic Books","Sports|Olympic Sports","Automotive|Auto Buying and Selling","Business and Finance|Industries|Advertising Industry","Sports|Field Hockey","Hobbies & Interests|Content Production|Screenwriting","Medical Health|Cosmetic Medical Services","Events and Attractions|Personal Celebrations & Life Events|Birth","Travel|Travel Type|Business Travel","Business and Finance|Industries|Entertainment Industry","Television|Soap Opera TV","Sports|Beach Volleyball","Personal Finance|Insurance|Health Insurance","Medical Health|Diseases and Conditions|Reproductive Health|Pregnancy","Medical Health|Diseases and Conditions|Endocrine and Metabolic Diseases","Real Estate|Office Property","Sports|Fantasy Sports","Automotive|Auto Body Styles|Crossover","Personal Finance|Insurance|Motor Insurance","Hobbies & Interests|Antiquing and Antiques","Personal Finance|Personal Debt|Student Loans","Sports|Extreme Sports|Canoeing and Kayaking","Real Estate|Apartments","Sports|Inline Skating","Pets|Pet Adoptions","Sports|Bowling","Technology & Computing|Computing|Data Storage and Warehousing","Sports|Extreme Sports|Scuba Diving","Hobbies & Interests|Cigars","Careers|Apprenticeships","Style & Fashion|Personal Care|Shaving","Healthy Living|Wellness|Smoking Cessation","Automotive|Road-Side Assistance","Movies|World Movies","Business and Finance|Business|Business Banking & Finance|Bankruptcy","Music and Audio|Talk Radio|News Radio","Food & Drink|Food Allergies","Automotive|Auto Shows","Technology & Computing|Computing|Computer Software and Applications|Desktop Publishing","Automotive|Auto Type|Certified Pre-Owned Cars","Personal Finance|Personal Investing|Hedge Funds","Business and Finance|Industries|Education industry","Style & Fashion|Beauty|Nail Care","Medical Health|Diseases and Conditions|Endocrine and Metabolic Diseases|Thyroid Disorders","Sports|Extreme Sports|Paintball","Education|Primary Education","Business and Finance|Industries|Management Consulting Industry","Hobbies & Interests|Arts and Crafts|Beadwork","Technology & Computing|Computing|Computer Software and Applications|Web Conferencing","Medical Health|Diseases and Conditions|Endocrine and Metabolic Diseases|Menopause","Hobbies & Interests|Collecting|Stamps and Coins","Education|Private School","Events and Attractions|Personal Celebrations & Life Events|Prom","Music and Audio|Sports Radio","Shopping|Gifts and Greetings Cards","Sports|Extreme Sports|Climbing","Personal Finance|Insurance|Travel Insurance","Business and Finance|Business|Small and Medium-sized Business","Careers|Career Planning","Sports|Extreme Sports|Waterskiing and Wakeboarding","Automotive|Auto Type|Driverless Cars","Family and Relationships|Eldercare","Travel|Travel Locations|Polar Travel","Technology & Computing|Computing|Computer Software and Applications|Antivirus Software","Music and Audio|Talk Radio|Educational Radio","Business and Finance|Business|Business Banking & Finance|Sale & Lease Back"], "example": ["Sports|Cycling", "Sports", "Music and Audio|Talk Radio|Public Radio", "Music and Audio|Talk Radio", "Music and Audio"] }, "audience_segment": { "type": "array", "items": { "type": "string" }, "description": "Data type: `uid`\n \nLarge custom-built filters, referenced by their unique IDs. Please contact support if you'd like to learn more.", "example": ["au_IoicnmcBkFa"] }, "us_dma": { "type": "array", "items": { "type": "string" }, "description": "Data type: `uid`\n \nGeographic filter on United States metropolitan area.", "enum": ["abilenesweetwatertx","albanyga","albanyschenectadytroyny","albuquerquesantafenm","alexandriala","alpenami","amarillotx","anchorageak","atlantaga","augustaga","austintx","bakersfieldca","baltimoremd","bangorme","batonrougela","beaumontportarthurtx","bendor","billingsmt","biloxigulfportms","binghamtonny","birminghamannistonandtuscaloosaal","bluefieldbeckleyoakhillwv","boiseid","bostonmamanchesternh","bowlinggreenky","buffalony","burlingtonvtplattsburghny","buttebozemanmt","casperrivertonwy","cedarrapidswaterlooiowacitydubuqueia","champaignspringfielddecaturil","charlestonhuntingtonwv","charlestonsc","charlottenc","charlottesvilleva","chattanoogatn","cheyennewyscottsbluffne","chicagoil","chicoreddingca","cincinnatioh","clarksburgwestonwv","clevelandakroncantonoh","coloradospringspuebloco","columbiajeffersoncitymo","columbiasc","columbusga","columbusoh","columbustupelowestpointms","corpuschristitx","dallasftworthtx","davenportiarockislandmolineil","daytonoh","denverco","desmoinesamesia","detroitmi","dothanal","duluthmnsuperiorwi","elmirany","elpasotx","eriepa","eugeneor","eurekaca","evansvillein","fairbanksak","fargovalleycitynd","flintsaginawbaycitymi","fresnovisaliaca","ftmyersnaplesfl","ftsmithfayettevillespringdalerogersar","ftwaynein","gainesvillefl","glendivemt","grandjunctionmontroseco","grandrapidskalamazoobattlecreekmi","greatfallsmt","greenbayappletonwi","greensborohighpointwinstonsalemnc","greenvillenewbernwashingtonnc","greenvillespartanburgscashevillencandersonsc","greenwoodgreenvillems","harlingenweslacobrownsvillemcallentx","harrisburglancasterlebanonyorkpa","harrisonburgva","hartfordnewhavenct","hattiesburglaurelms","helenamt","honoluluhi","houstontx","huntsvilledecaturflorenceal","idahofallspocatelloid","indianapolisin","jacksonms","jacksontn","jacksonvillefl","johnstownaltoonapa","jonesboroar","joplinmopittsburgks","juneauak","kansascitymo","knoxvilletn","lacrosseeauclairewi","lafayettein","lafayettela","lakecharlesla","lansingmi","laredotx","lasvegasnv","lexingtonky","limaoh","lincolnhastingskearneyne","littlerockpinebluffar","losangelesca","louisvilleky","lubbocktx","maconga","madisonwi","mankatomn","marquettemi","medfordklamathfallsor","memphistn","meridianms","miamifortlauderdalefl","milwaukeewi","minneapolisstpaulmn","minotbismarckdickinsonwillistonnd","missoulamt","mobilealpensacolaftwaltonbeachfl","monroelaeldoradoar","montereysalinasca","montgomeryselmaal","myrtlebeachflorencesc","nashvilletn","neworleansla","newyorkny","norfolkportsmouthnewportnewsva","northplattene","odessamidlandtx","oklahomacityok","omahane","orlandodaytonabeachmelbournefl","ottumwaiakirksvillemo","paducahkycapegirardeaumoharrisburgil","palmspringsca","panamacityfl","parkersburgwv","peoriabloomingtonil","philadelphiapa","phoenixaz","pittsburghpa","portlandauburnme","portlandor","presqueisleme","providencerinewbedfordma","quincyilhannibalmokeokukia","raleighdurhamfayettevillenc","rapidcitysd","renonv","richmondpetersburgva","roanokelynchburgva","rochestermnmasoncityiaaustinmn","rochesterny","rockfordil","sacramentostocktonmodestoca","salisburymd","saltlakecityut","sanangelotx","sanantoniotx","sandiegoca","sanfranciscooaklandsanjoseca","santabarbarasantamariasanluisobispoca","savannahga","seattletacomawa","shermantxadaok","shreveportla","siouxcityia","siouxfallsmitchellsd","southbendelkhartin","spokanewa","springfieldholyokema","springfieldmo","stjosephmo","stlouismo","syracuseny","tallahasseeflthomasvillega","tampastpetersburgsarasotafl","terrehautein","toledooh","topekaks","traversecitycadillacmi","tricitiestnva","tucsonsierravistaaz","tulsaok","twinfallsid","tylerlongviewlufkinnacogdochestx","uticany","victoriatx","wacotemplebryantx","washingtondchagerstownmd","watertownny","wausaurhinelanderwi","westpalmbeachftpiercefl","wheelingwvsteubenvilleoh","wichitafallstxlawtonok","wichitahutchinsonksplus","wilkesbarrescrantonpa","wilmingtonnc","yakimapascorichlandkennewickwa","youngstownoh","yumaazelcentroca","zanesvilleoh"], "example": ["kansascitymo"] }, "us_state": { "type": "array", "items": { "type": "string" }, "description": "Data type: `uid`\n \nGeographic filter on United States State or Territory.", "enum": ["ak","al","ar","az","ca","co","ct","dc","de","fl","ga","hi","ia","id","il","in","ks","ky","la","ma","md","me","mi","mn","mo","ms","mt","nc","nd","ne","nh","nj","nm","nv","ny","oh","ok","or","pa","pr","ri","sc","sd","tn","tx","ut","va","vt","wa","wi","wv","wy"], "example": ["mo"] }, "ca_province": { "type": "array", "items": { "type": "string" }, "description": "Data type: `uid`\n \nGeographic filter on Canadian Province.", "enum": ["on","qc","ns","nb","mb","bc","pe","sk","ab","nl","nt","yt","nu"], "example": ["on"] }, "adult_content": { "type": "boolean", "description": "Infegy IQ classifies incoming content as \"adult content\", such as pornography and dense adult language. Content tagged as such will have this value set to \"true\". Please note that this detection started 2026-04-07T22:05:00Z, meaning any content collected prior to that date will have this value set to false." } } }, "Query": { "title": "Query definition", "description": "All data operations in Starscape start with a Query, used to specify what data is desired for analysis or retrieval. This is a nestable object of operators, as simple as a single leaf operator, or nearly limitlessly deep, as needed.", "type": "object", "anyOf": [ { "type": "object", "title": "and", "description": "Requires all sub-values match.", "properties": { "op": { "type": "string", "const": "and" }, "values": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/Query" } } }, "required": [ "op", "values" ], "example": { "op": "and", "values": [ { "op": "contains", "field": "body", "value": "recipe" }, { "op": "range", "field": "published", "comparison": "gte_lt", "lower": "2024-01-01", "upper": "2024-04-01" }, { "op": "or", "values": [ { "op": "contains", "field": "language", "values": ["en", "fr"] }, { "op": "contains", "field": "country", "value": "fr" } ] } ] } }, { "type": "object", "title": "or", "description": "Requires at least `quorum` sub-values match.", "properties": { "op": { "type": "string", "const": "or" }, "quorum": { "type": "integer", "default": 1, "description": "At least this number of sub-values must match for the `or` operator to match." }, "values": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/Query" } } }, "required": [ "op", "values" ] }, { "type": "object", "title": "not", "description": "Requires none of the sub-values match (or less than the quorum).", "properties": { "op": { "type": "string", "const": "not" }, "quorum": { "type": "integer", "default": 1, "description": "If set above 1, the `not` operator will allow up to N-1 values and still match. For example, a `quorum` of 2 will match if only a single sub-value matches, but not if any more than 1 match." }, "values": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/Query" } } }, "required": [ "op", "values" ] }, { "type": "object", "title": "span", "description": "Requires `left` and `right` have matches with a minimum distance less than or equal to `distance`. This operator requires a field be specified, which will be applied to all sub-clauses in `left` and `right` (their `field` value may be omitted). The field must be a text type, as it is the only field type with positional information.\n \n*Supported field types*: text", "properties": { "op": { "type": "string", "const": "span" }, "distance": { "type": "integer", "default": 1, "description": "The minimum distance between any matching pair of clauses within `left` and `right`." }, "ordered": { "type": "boolean", "default": false, "description": "If true, `left` must come before `right`. If false (the default) the ordering is ignored - as in the absolute value of the distance is used." }, "left": { "$ref": "#/components/schemas/Query" }, "right": { "$ref": "#/components/schemas/Query" } }, "required": [ "op", "distance", "left", "right" ] }, { "type": "object", "title": "boolean", "description": "Allows use of full boolean queries, provided as the operators `value`. Multiple fields are allowed. Example: `(apple OR oranges) NEAR/3 \"fruit basket\"`\n \n*Supported field types*: text, keyword, keywords", "properties": { "op": { "type": "string", "const": "boolean" }, "fields": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "value": { "type": "string" } }, "required": [ "op", "fields", "value" ] }, { "type": "object", "title": "contains", "description": "Matches documents that contain one or more (configurable with the `quorum` option) of the specified `values` in one or more of the specified `fields`.\n \n*Supported field types*: text, keyword, keywords, timestamp, integer, decimal, boolean, uid.\nSupports null value, matching when the specified field is not present.", "properties": { "op": { "type": "string", "const": "contains" }, "fields": { "description": "If a single field is used, the singular `field` property can be used instead.", "type": "array", "minItems": 1, "items": { "type": "string" } }, "values": { "description": "If a single value is used, the singular `value` property can be used instead.", "type": "array", "minItems": 1, "items": { "types": ["string", "number", "null", "boolean"] } } }, "required": [ "op", "fields", "values" ] }, { "type": "object", "title": "= (equals)", "description": "Exact matching, the field's value must match the provided value. For keywords (plural) types, all provided values must be contained within the field, but the field may have additional values. For most cases, this behavior will match the `contains` operator.\n \n*Supported field types*: keyword, keywords, timestamp, integer, decimal, boolean, null, uid.\nSupports null value, matching when the specified field is not present.", "properties": { "op": { "type": "string", "const": "=" }, "field": { "type": "string" }, "value": { "types": ["string", "number", "null", "boolean"] } } }, { "type": "object", "title": "< (less-than)", "description": "Compare the field's value to the provided. The field is the left-hand side of the comparison, with the provided query value on the right.\n \n*Supported field types*: timestamp, integer, decimal.", "properties": { "op": { "type": "string", "const": "<" }, "field": { "type": "string" }, "value": { "types": ["string", "number"] } } }, { "type": "object", "title": "<= (less-than-or-equal)", "description": "Compare the field's value to the provided. The field is the left-hand side of the comparison, with the provided query value on the right.\n \n*Supported field types*: timestamp, integer, decimal.", "properties": { "op": { "type": "string", "const": "<=" }, "field": { "type": "string" }, "value": { "types": ["string", "number"] } } }, { "type": "object", "title": "> (greater-than)", "description": "Compare the field's value to the provided. The field is the left-hand side of the comparison, with the provided query value on the right.\n \n*Supported field types*: timestamp, integer, decimal.", "properties": { "op": { "type": "string", "const": ">" }, "field": { "type": "string" }, "value": { "types": ["string", "number"] } } }, { "type": "object", "title": ">= (greater-than-or-equal)", "description": "Compare the field's value to the provided. The field is the left-hand side of the comparison, with the provided query value on the right.\n \n*Supported field types*: timestamp, integer, decimal.", "properties": { "op": { "type": "string", "const": ">=" }, "field": { "type": "string" }, "value": { "types": ["string", "number"] } } }, { "type": "object", "title": "range", "description": "Compare against a range. The query value must be between the range. By default for numeric fields, this will be Greater-Than-or-Equal (gte) to the `lower` value, and Less-Than-or-Equal (lte) to the `upper` value. Timestamp fields default to gte_lt (greater than or equal to lower, and less than upper) to make date comparisons easier without knowing the field precision.\n \n*Supported field types*: timestamp, integer, decimal.", "properties": { "op": { "type": "string", "const": "range" }, "field": { "type": "string" }, "lower": { "types": ["string", "number"], "description": "The lower value of the range to match. The value must be greater-than (or possibly equal to based on `comparison`) to this to match." }, "upper": { "types": ["string", "number"], "description": "The upper value of the range to match. The value must be less-than (or possibly equal to based on `comparison`) to this to match." }, "comparison": { "type": "string", "enum": ["gt_lt", "gte_lt", "gt_lte", "gte_lte"], "default": "gte_lte", "description": "Abbreviations of Greater-Than (gt), Greater-Than-or-Equal (gte), Less Than (lt), Less-Than-or-Equal (lte), controlling the operation used for the range." }, "required": [ "field", "lower", "upper" ] } }, { "type": "object", "title": "id", "description": "Match individual records based on their unique identifiers, seen as the \"_id\" field in /records, or \"id\" in cluster-graph. Provide one or more IDs in the `values` array.", "properties": { "op": { "type": "string", "const": "id" }, "values": { "type": ["array"] } } } ] }, "AggQuery": { "type": "object", "title": "Aggregation definition", "description": "Aggregation definition objects provide specifications for desired aggregations to the `/query/agg` endpoint. These are keyed by a user-provided identifier, used to identify that result, with the same key, in the response.", "properties": { "YOUR_AGG_KEY": { "anyOf": [ { "type": "object", "title": "histogram", "description": "Groups values into buckets. The size of these buckets is controllable using the `interval` parameter. For example, if we use an `interval` of 20, we will get a bucket every 20 values, from the minimum seen to the maximum seen.\n \nWhen using a timestamp field, histograms allow specifying a `bucket_count` instead of `interval`, which will create the specified number of buckets automatically. Additionally, timestamp histograms accept time values for the `interval`, to group within a known unit. Supported time intervals are: \"millisecond\"*, \"second\", \"minute\", \"hour\", \"day\", \"week\", \"month\", \"quarter\", \"year\".\n* \"millisecond\" is only supported if the field used has millisecond or better precision.\n \nIf you specify a timestamp field, and do not specify `bucket_count` or `interval`, a `bucket_count` of 31 will be used.\n \nIf you specify a non-timestamp field, an `interval` is required if the field does not have a known min and max.\n \nhistogram results will contain an array of `_buckets`, which always contain, at minimum, a `_count` value for the number of matching results within that bucket.", "properties": { "op": { "type": "string", "const": "histogram" }, "field": { "type": "string", "description": "Field ID - must be of type timestamp, decimal, integer (without the index_as_keyword attribute)." }, "interval": { "types": ["string", "integer"], "description": "For timestamp fields, one of: millisecond, second, minute, hour, day, week, month, quarter, year, auto; for numeric fields, a spacing value between buckets." }, "bucket_count": { "type": "integer", "default": 31, "description": "Field type must be timestamp; Number of buckets to output, optionally used instead of interval." }, "fill_range": { "type": "boolean", "default": true, "description": "If true (default), we will fill in missing buckets, caused by no matches for the query, back to the start of the filtered range on the aggregated field, as well as to the end of the filtered range of the aggregated field. If this is false, the resulting range may start after the filtered range, at the point of the first match, or end prior to the end of the filter, at the point of the last match." }, "aggs": { "$ref": "#/components/schemas/AggQuery" } }, "required": [ "op", "field" ] }, { "type": "object", "title": "keyword", "description": "Groups results by values seen in the field (note that latitude_longitude are treated as geohashes). Provide `bucket_count` to limit the number of results to the top N (by matches). `bucket_count` defaults to 20 if not specified.\n \nSpecify `include_null`: true to include a special value with the key of JSON null, and the label “[missing]”, which is the total number of matches that did not have this field.\nNOTE: If the field type is boolean, `include_null` will count missing values as false.\n \nSpecify `include_other`: true to include a special value with the key of “__other__”, which is the total number of matches that aren’t listed in the top buckets, but had the field. If you display results as a ratio, this should always be used and included!\n \nkeyword aggregations can be filtered. This can be particularly useful when combined with percent, or if you only care about specific values. Note that these must be the “key” of a bucket, NOT its label!", "properties": { "op": { "type": "string", "const": "keyword" }, "field": { "type": "string", "description": "Field ID - must be of type keyword, keywords, or integer with index_as_keyword attribute." }, "bucket_count": { "type": "integer", "default": 20, "description": "Maximum number of buckets to output." }, "include_null": { "type": "boolean", "default": false, "description": "If set to true, we will count records wherein this field is missing as a special key of __null__" }, "include_other": { "type": "boolean", "default": false, "description": "If set to true, we will include a bucket with the special key of __other__ counting the total results not included in the output buckets." }, "filter": { "type": "array", "values": "string", "description": "An array of values to include in the output (excluding all others)." }, "exclude": { "type": "array", "values": "string", "description": "An array of values to exclude from the output." }, "sort": { "description": "Specify a sort field and direction to order the results, defaulting to the _count field in `desc` (descending) order", "type": "object", "properties": { "field": { "description": "The field on which to order the results. Defaults to `_count`. Accepts `_count`, `_key` (the bucket key/name), or a sub-aggregation name. Note: Ordering by `_count` `asc` (ascending _count) will result in an error, as this is not supported.", "type": "string", "default": "_count" }, "direction": { "description": "The direction to order, either `asc` (ascending, smallest to largest), or `desc` (descending, largest to smallest), defaulting to `desc`", "type": "string", "enum": ["asc", "desc"], "default": "desc" } } }, "aggs": { "$ref": "#/components/schemas/AggQuery" } }, "required": [ "op", "field" ] }, { "type": "object", "title": "percent", "description": "This will add a single value to each parent bucket of the percentage of that parent buckets this value comprises, considering totals not included in the buckets - MUST be a sub-agg under a histogram or keyword agg. If `of_total` is true, this will be based on the parent's parent bucket total, which may be the whole query's total, rather than a sum of the parent buckets otherwise.", "properties": { "op": { "type": "string", "const": "percent" }, "of_total": { "type": "boolean", "default": false } }, "required": [ "op" ] }, { "type": "object", "title": "percentile", "description": "Computes an estimated percentile rank on the given field for each bucket in the parent.", "properties": { "op": { "type": "string", "const": "percentile" }, "field": { "type": "string", "description": "Field ID - must be of type integer or decimal" }, "percentile": { "types": ["number"], "description": "Specify the rank desired. For example, a value of 95 (or 0.95) would give a 95th percentile rank, meaning 95% of the values are at or below the output values. This example is commonly referred to as the “p95”" } }, "required": [ "op", "field", "percentile" ] }, { "type": "object", "title": "min", "description": "Returns the minimum value seen in the field.", "properties": { "op": { "type": "string", "const": "min" }, "field": { "type": "string", "description": "Field ID - must be of type integer, decimal, or timestamp" } }, "required": [ "op", "field" ] }, { "type": "object", "title": "max", "description": "Returns the maximum value seen in the field.", "properties": { "op": { "type": "string", "const": "max" }, "field": { "type": "string", "description": "Field ID - must be of type integer, decimal, or timestamp" } }, "required": [ "op", "field" ] }, { "type": "object", "title": "sum", "description": "Returns the sum (total) of all values seen in the field.", "properties": { "op": { "type": "string", "const": "sum" }, "field": { "type": "string", "description": "Field ID - must be of type integer or decimal" } }, "required": [ "op", "field" ] }, { "type": "object", "title": "avg", "description": "Returns the arithmetic mean (sometimes known as the average) of all values seen in the field.", "properties": { "op": { "type": "string", "const": "avg" }, "field": { "type": "string", "description": "Field ID - must be of type integer or decimal" } }, "required": [ "op", "field" ] }, { "type": "object", "title": "median", "description": "Returns an estimate of the median (middle value) of all values seen in the field.", "properties": { "op": { "type": "string", "const": "median" }, "field": { "type": "string", "description": "Field ID - must be of type integer or decimal" } }, "required": [ "op", "field" ] }, { "type": "object", "title": "social_universe", "description": "Returns the Social Universe score. This operator is specific to the Infegy Social dataset, and won't work elsewhere.", "properties": { "op": { "type": "string", "const": "social_universe" } }, "required": [ "op" ] } ] } }, "required": [ "YOUR_AGG_KEY" ], "example": { "weekly histogram": { "op": "histogram", "field": "published", "interval": "week" }, "sentiment totals": { "op": "keyword", "field": "sentiment", "include_null": true, "aggs": { "percent": { "op": "percent" } } } } }, "RecordsQuery": { "title": "Records definition", "description": "Records definition objects provide options to the `/query/records` endpoint. All properties, even the whole object, are optional.", "type": "object", "properties": { "size": { "description": "How many results you'd like returned. This will accept up to 25,000, and even more if using fewer fields.\nIf you request no text field types, the maximum will increase to 60,000. Additionally, if there are fewer than 5 fields requested, the maximum will be multiplied by 6 - the field count. For example, if we request 3 fields, the maximum will be multiplied by (6 - 3) = 3, giving us 60,000 if we request text fields, or 180,000 without text fields.", "type": "integer", "default": 10, "minimum": 1, "maximum": 25000 }, "fields": { "description": "Limit fields returned. These should be field ID values. Any valid IDs that exist in the dataset are acceptable here. Specifying the exact fields you’d like can greatly reduce response size, as well as increase the number of records you can get per request (see `size` above).\n \nAn array of strings, each a field ID, is allowed. Alternatively, if selecting a single field, a string specifying a single field ID is allowed. There is also a special value of “*” indicating all fields. This is the default behavior, so is not required to be specified.\n \nFields specified must have the \"stored\" attribute set to true (returned from query-info). Attempts to request a field otherwise will return an error.", "type": "array", "minItems": 1, "items": { "type": "string" } }, "sort": { "description": "Specify a sort order with one or more fields. This allows retrieving the top results ordered by a given field value, by sorting the full query result.\n \nThe input is an array of objects, each of which must contain a “field” member, which is a valid field ID in the dataset. This field must be a decimal, integer, or timestamp type. They can contain an optional additional “direction” member, which indicates ordering. This defaults to “desc”, meaning descending order (highest values first). It also accepts “asc”, ascending order (lowest values first).\n \nNote: Specifying sorting will not return pagination information required to iterate through results. If you require sorting, the maximum number of results returned for a given query is the maximum size of a single request (see `size` above). If sorting is not specified, the `cursor` and `since` values will be returned in the result, enabling iterative retrieval of a much larger number of results per query. This default ordering will be roughly by time added, newest first.", "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "direction": { "type": "string", "enum": ["asc", "desc"], "default": "desc" } }, "required": [ "field" ] } }, "flatten_output": { "description": "If true, the output structure will be flattened, by providing field_ids and field_labels in top-level arrays, then returning records as an array of arrays, with each value taking an index aligned with field_ids. This avoids repeating the keys for every object, which can reduce output size significantly - though if there are many null fields read, it is less effective, as the nulls must be written to the arrays, as opposed to simply not writing the field in the object structure.\n \nFlattening becomes especially powerful when selecting a single field. In this case, the output is condensed further, to a single-depth array of values indexed by record in the result. And when requesting fewer fields, we will allow returning more results per request.", "type": "boolean", "default": false }, "use_longitude_latitude": { "description": "If true, coordinate order for latitude_longitude (location) fields will be flipped, returning in longitude, latitude order instead. This is useful when the data is going into a GeoJSON-style system, which typically uses this ordering rather than the more common latitude, longitude ordering we default to.", "type": "boolean", "default": false }, "strip_html": { "description": "If `true`, HTML will be removed from text fields that contain it, including the resolution of HTML entities like &. This option defaults to `true` for CSV format, `false` for others.", "type": "boolean", "default": false }, "cursor": { "description": "Provide a cursor from a previous response to get the next set of results from that cursor position. This is used to retrieve more results from a query than the maximum size will allow at once. This can be used to return all results matching a given query, simply by running the query repeatedly, providing the previous response cursor each time, until the cursor value is null, indicating no further results.\n \nNote: cursor is only provided in responses that do NOT specify `sort`, as noted in `sort`.", "type": "string" }, "since": { "description": "Provide a since from a previous response to get results added to the dataset since the last query was run (when the `since` parameter was generated). Use this to get new results added since your last run, as a reverse cursor. If the query returns no results, nothing new was added, and the output `since` value will remain the same as your input. Unlike `cursor`, `since` will never be null if a value was given in the query. Instead, you know you've retreived all of the latest results when the query returns less than you requested.\n \nNote: since is only provided in responses that do NOT specify `sort`, as noted in `sort`.", "type": "string" }, "match_info": { "description": "Outputs an additional object on records with the key `_match_info`, this object keyed by field IDs, indicating what, in the record, matched the query. If highlighting is enabled, this defaults to true. Match info is only supported for non-flattened JSON output.", "type": "boolean", "default": false }, "highlight": { "description": "Enable and configure query match text highlighting. Set `pre` to the string to prepend (insert at the place of a query match), and `post` to the text to insert at the end, after the query match. This is used to mark where, in text fields, the query matched the text. For example, `pre` could be set to something like: \"<span class='query-match'>\" and post to: \"</span>\". Note: Highlighting is enabled by setting either/both of `pre`/`post`. If highlighting is enabled, strip_html is force-enabled as well.", "type": "object", "properties": { "pre": { "type": "string" }, "post": { "type": "string" } } } } }, "TopicsQuery": { "title": "Topics definition", "description": "Topics definition objects provide options to the `/query/topics` endpoint. All properties, even the whole object, are optional.", "type": "object", "properties": { "size": { "description": "Number of results to return.", "type": "integer", "default": 50, "minimum": 1, "maximum": 1000 }, "fields": { "description": "Limit fields to use for analysis. By default, any fields marked for analyze at ingest time will be used. This information is available via `/query/info`.\n \nAccepts field ids, and the fields must be of type text.", "type": "array", "minItems": 1, "items": { "type": "string" } }, "sort": { "description": "Specify sort ordering for the output topics.", "type": "string", "enum": ["relevance", "count", "appearances", "rising", "falling"], "default": "relevance" }, "sample_sort": { "description": "Specify a sort order with one or more fields for the data sampling, if required. For example, if the query has 1,000,000 results, and we analyze 50,000 by default, you can specify sorting to analyze the top 50,000 by a given field. By default, ordering is repeatably random, ensuring an evenly distributed sample.", "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "direction": { "type": "string", "enum": ["asc", "desc"], "default": "desc" } }, "required": [ "field" ] } }, "types": { "description": "Specify the topic type(s) you'd like returned.\n \n* *topic*: Key words and phrases\n* *hashtag*: #hashtags\n* *mention*: social media-style @mentions\n* *link*: Web links, must contain a protocol with ://\n* *domain*: Domains seen in links, like infegy.com\n* *emoji*: Emoji seen, like 👋\n* *flag*: Emoji flags, such as 🇺🇸", "type": "array", "items": { "enum": ["topic", "hashtag", "mention", "link", "domain", "emoji", "flag"] }, "minItems": 1, "default": ["topic"] }, "filter": { "type": "array", "values": "string", "description": "An array of values to include in the output (excluding all others)." }, "exclude": { "type": "array", "values": "string", "description": "An array of values to exclude from the output." }, "phrases_match_unigrams": { "type": "boolean", "default": false, "description": "If true, phrases in filter and exclude will also consider their unigrams. For example, \"hello world\" will also match \"hello\" or \"world\"" }, "query_term_exclusion": { "description": "Controls handling of query terms for the analysis. By default, any terms in the query are ignored. If this is set to `required`, only terms in a top-level `and` operator, or stand-alone leaves, will be excluded. If set to `none`, query terms will be processed as any other text. If set to `only`, ONLY terms appearing in the query will be output.", "type": "string", "enum": ["all", "required", "none", "only"], "default": "all" }, "sample_size": { "description": "Controls the maximum number of records that will be analyzed. Higher values will increase response latency.", "type": "integer", "minimum": 1, "maximum": 100000, "default": 50000 }, "clustering_bias": { "description": "Bias control for clustering. Lower values will lead to less propensity for topics to be clustered together, with higher values making the clustering system more promiscuous.", "type": "decimal", "minimum": 0.0, "maximum": 1.0, "default": 0.5 } } }, "ClustersQuery": { "title": "Clusters definition", "description": "Clusters definition objects provide options to the `/query/clusters` and `/query/cluster-graph` endpoints. All properties, even the whole object, are optional.", "type": "object", "properties": { "size": { "description": "cluster-graph only: The maximum number of record nodes to return in the result. `sample_size` will be set to this value if this value is larger than `sample_size`. This option has no effect for the /clusters endpoint, it is specifically for /clusters-graph.", "type": "integer", "default": 1000, "minimum": 1, "maximum": 100000 }, "fields": { "description": "Limit fields to use for analysis. By default, any fields marked for analyze at ingest time will be used. This information is available via `/query/info`.\n \nAccepts field ids, and the fields must be of type text.", "type": "array", "minItems": 1, "items": { "type": "string" } }, "sample_sort": { "description": "Specify a sort order with one or more fields for the sampling, if required. For example, if the query has 1,000,000 results, and we analyze 50,000 by default, you can specify sorting to analyze the top 50,000 by a given field. By default, ordering is repeatably random, ensuring an evenly distributed sample.", "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "direction": { "type": "string", "enum": ["asc", "desc"], "default": "desc" } }, "required": [ "field" ] } }, "exclude": { "type": "array", "values": "string", "description": "An array of terms to exclude from analysis of clustering." }, "query_term_exclusion": { "description": "Controls handling of query terms for the analysis. By default, any terms in the query are ignored. If this is set to `required`, only terms in a top-level `and` operator, or stand-alone leaves, will be excluded. If set to `none`, query terms will be processed as any other text.", "type": "string", "enum": ["all", "required", "none"], "default": "all" }, "sample_size": { "description": "Controls the maximum number of records that will be analyzed. Higher values will increase response latency.", "type": "integer", "minimum": 1, "maximum": 100000, "default": 50000 }, "clustering_bias": { "description": "Bias control for clustering. Lower values will lead to less propensity for records to be clustered together, with higher values making the clustering system more promiscuous.", "type": "decimal", "minimum": 0.0, "maximum": 1.0, "default": 0.5 } } } } }, "security": [ { "api_token": [] } ], "paths": { "/query/test": { "post": { "description": "# Query Test\nTest and verify a query is ok and runnable with a rapid-response no-cost endpoint.", "requestBody": { "required": true, "description": "Query", "content": { "application/json": { "schema": { "type": "object", "properties": { "dataset_id": { "type": "string", "description": "Identifier of the dataset to query. Your authentication token must have permission to read from this dataset. If not specified, and you have access to the social dataset, the social dataset (id `ds_gj4u3F40SLa`) will be used." }, "timezone": { "type": "string", "description": "IANA timezone to use for interpreting input query times - NOT used on output", "default": "Etc/UTC" }, "query": { "$ref": "#/components/schemas/Query" } }, "required": [ "query", "aggs" ] }, "example": { "dataset_id": "ds_gj4u3F40SLa", "query": { "op": "contains", "fields": ["title", "body"], "value": "recipe" } } } } }, "responses": { "200": { "description": "Query is OK!\n \nThe response will contain output similar to the input, with the query optimized and normalized. For example, redundant nodes will be removed and boolean operators will be expanded." }, "400": { "description": "Your request has a problem.\n \nNote the response body for more information on what is wrong, and possibly how to fix it." }, "401": { "description": "Missing or invalid authentication.\n \nEnsure your provided Authorization token is correct and valid." }, "402": { "description": "Authentication credentials provided were valid, but one or more required permissions is missing, or access to one or more resources is lacking." }, "403": { "description": "Authentication failure.\n \nThere is a problem with the provided credentials. You likely lack permissions for the dataset used, or may need a new API token. Additional details may be provided in the response body." }, "413": { "description": "The request timed out. Likely due to taking too long to process. Should this unlikely error occur, try reducing the complexity of your query or narrowing the volume of results. Don't hesitate to reach out to support for assistance!" }, "500": { "description": "Server error.\n \nThere was an error handling your request. Feel free to wait a bit and try again. Note that any such errors are recorded, and notify our team - we will make every effort to fix any issues as quickly as possible." }, "503": { "description": "One or more backend services failed to respond, and we gave up waiting. Please wait a bit and try again. Don't hestitate to reach out to support for assistance." } } } }, "/query/info": { "post": { "description": "# Query Info\nRetrieve details on fields avaiable within a dataset, along with query options. Provides all field IDs, labels, types, traits such as aggregation support, query support, analysis default, ranges (where known), and values in keyword/s and uid fields (where known).\nCritical for understanding what fields are avaiable for query, aggregation, and analysis.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "dataset_id": { "type": "string", "description": "Identifier of the dataset to query. Your authentication token must have permission to read from this dataset. If not specified, and you have access to the social dataset, the social dataset (id `ds_gj4u3F40SLa`) will be used." } } }, "example": { "dataset_id": "ds_gj4u3F40SLa" } } } }, "responses": { "200": { "description": "Query information returned." }, "400": { "description": "Your request has a problem.\n \nNote the response body for more information on what is wrong, and possibly how to fix it." }, "401": { "description": "Missing or invalid authentication.\n \nEnsure your provided Authorization token is correct and valid." }, "402": { "description": "Authentication credentials provided were valid, but one or more required permissions is missing, or access to one or more resources is lacking." }, "403": { "description": "Authentication failure.\n \nThere is a problem with the provided credentials. You likely lack permissions for the dataset used, or may need a new API token. Additional details may be provided in the response body." }, "413": { "description": "The request timed out. Likely due to taking too long to process. Should this unlikely error occur, try reducing the complexity of your query or narrowing the volume of results. Don't hesitate to reach out to support for assistance!" }, "500": { "description": "Server error.\n \nThere was an error handling your request. Feel free to wait a bit and try again. Note that any such errors are recorded, and notify our team - we will make every effort to fix any issues as quickly as possible." }, "503": { "description": "One or more backend services failed to respond, and we gave up waiting. Please wait a bit and try again. Don't hestitate to reach out to support for assistance." } } } }, "/query/agg": { "post": { "description": "# Aggregate\nThe primary means of analytics, aggregation bins data matching the query, possibly performing mathematical operations on the way. So rather than returning documents, this endpoint will return metrics. These aggregations can be nested, enabling a wealth of information from a relatively simple specification.\n \nAggregation is relatable to a SQL GROUP BY operation.\n \nAggregations are specified as their own object structure, provided in the body of the request. If you provide both a query and an aggregation structure in the same request body, the top-level query object should have the aggregation structure within an `aggs` member.\n \n \n### Example\nBelow is a more complex example request body. We will simply query for records mentioning \"iphone\". Our aggregations will give us a `histogram` by day (day-by-day data), with each day containing total matches as `_count` (always included), along with a sub-aggregation we called \"Sentiment\". This is a `keyword` aggregation that will give us poisitive, negative, and neutral counts for each day. We'll also include a sub-aggregation called \"Countries\", which will give us counts for the top 5 countries for each day. Lastly, this Countries aggregation includes its own sub-aggregation, called \"%\", which uses the `percent` op to give us a percentage for each country, in addition to the record count. Quite a lot of information from one request!\n```json\n{\n \"dataset_id\": \"ds_gj4u3F40SLa\",\n \"query\": {\n \"op\": \"contains\",\n \"field\": \"body\",\n \"value\": \"iphone\"\n },\n \"aggs\": {\n \"Histogram\": {\n \"op\": \"histogram\",\n \"field\": \"published\",\n \"interval\": \"day\",\n \"aggs\": {\n \"Sentiment\": {\n \"op\": \"keyword\",\n \"field\": \"sentiment\"\n },\n \"Countries\": {\n \"op\": \"keyword\",\n \"field\": \"country\",\n \"bucket_count\": 5,\n \"aggs\": {\n \"%\": {\n \"op\": \"percent\"\n }\n }\n }\n }\n }\n }\n}\n```\n \n### Response\nHere is the beginning of the response, with the first bucket in the top-level histogram. Note the sentiment counts, top 5 countries, and the percentages added to each.\n \n```json\n{\n \"Histogram\": {\n \"_field_id\": \"published\",\n \"_field_label\": \"Published Date\",\n \"_buckets\": [\n {\n \"_key\": \"2024-06-25T00:00:00Z\",\n \"_label\": \"2024-06-25\",\n \"_count\": 25088,\n \"Sentiment\": {\n \"_field_id\": \"sentiment\",\n \"_field_label\": \"Sentiment\",\n \"_buckets\": [\n {\n \"_key\": \"0\",\n \"_label\": \"neutral\",\n \"_count\": 9479\n },\n {\n \"_key\": \"p\",\n \"_label\": \"positive\",\n \"_count\": 9154\n },\n {\n \"_key\": \"n\",\n \"_label\": \"negative\",\n \"_count\": 6455\n }\n ]\n },\n \"Countries\": {\n \"_field_id\": \"country\",\n \"_field_label\": \"Country\",\n \"_buckets\": [\n {\n \"_key\": \"us\",\n \"_label\": \"🇺🇸 United States of America\",\n \"_count\": 3244,\n \"%\": 0.18365036231884058\n },\n {\n \"_key\": \"id\",\n \"_label\": \"🇮🇩 Indonesia\",\n \"_count\": 1228,\n \"%\": 0.06951992753623189\n },\n {\n \"_key\": \"br\",\n \"_label\": \"🇧🇷 Brazil\",\n \"_count\": 1144,\n \"%\": 0.06476449275362318\n },\n {\n \"_key\": \"in\",\n \"_label\": \"🇮🇳 India\",\n \"_count\": 1051,\n \"%\": 0.05949954710144927\n },\n {\n \"_key\": \"de\",\n \"_label\": \"🇩🇪 Germany\",\n \"_count\": 792,\n \"%\": 0.04483695652173913\n }\n ]\n }\n }\n ]\n }\n}\n```", "parameters": [ { "name": "format", "in": "query", "description": "Choose the output format", "required": false, "schema": { "type": "string", "enum": ["json", "csv", "tsv"], "default": "json" } }, { "name": "include_total", "in": "query", "description": "If true, a numerical _total value will be added to the top-level output as the total results matching the input query.", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "flatten", "in": "query", "description": "Flattens JSON output format, returning an object with a series of flat arrays, rather than nested objects. Usable only with JSON output format.", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "fill_with_zero", "in": "query", "description": "When using flatten with JSON output, this will fill missing values in the flattened arrays with 0, rather than null.", "required": false, "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "description": "Aggregation query", "content": { "application/json": { "schema": { "type": "object", "properties": { "dataset_id": { "type": "string", "description": "Identifier of the dataset to query. Your authentication token must have permission to read from this dataset. If not specified, and you have access to the social dataset, the social dataset (id `ds_gj4u3F40SLa`) will be used." }, "timezone": { "type": "string", "description": "IANA timezone to use for interpreting input query times - NOT used on output", "default": "Etc/UTC" }, "query": { "$ref": "#/components/schemas/Query" }, "aggs": { "$ref": "#/components/schemas/AggQuery" } }, "required": [ "query", "aggs" ] }, "example": { "dataset_id": "ds_gj4u3F40SLa", "timezone": "Etc/UTC", "query": { "op": "contains", "fields": ["title", "body"], "value": "recipe" }, "aggs": { "weekly histogram": { "op": "histogram", "field": "published", "interval": "week" }, "sentiment totals": { "op": "keyword", "field": "sentiment" } } } } } }, "responses": { "200": { "description": "Successful aggregation response.\n \nThe result, if JSON, is an object, keyed using your provided aggregation keys in the request body." }, "400": { "description": "Your request has a problem.\n \nNote the response body for more information on what is wrong, and possibly how to fix it." }, "401": { "description": "Missing or invalid authentication.\n \nEnsure your provided Authorization token is correct and valid." }, "402": { "description": "Authentication credentials provided were valid, but one or more required permissions is missing, or access to one or more resources is lacking." }, "403": { "description": "Authentication failure.\n \nThere is a problem with the provided credentials. You likely lack permissions for the dataset used, or may need a new API token. Additional details may be provided in the response body." }, "413": { "description": "The request timed out. Likely due to taking too long to process. Should this unlikely error occur, try reducing the complexity of your query or narrowing the volume of results. Don't hesitate to reach out to support for assistance!" }, "500": { "description": "Server error.\n \nThere was an error handling your request. Feel free to wait a bit and try again. Note that any such errors are recorded, and notify our team - we will make every effort to fix any issues as quickly as possible." }, "503": { "description": "One or more backend services failed to respond, and we gave up waiting. Please wait a bit and try again. Don't hestitate to reach out to support for assistance." } } } }, "/query/records": { "post": { "description": "# Records\nRecords allows fetching individual results from the specified dataset, matching the given query. Records can be sorted to return the top N (using `size`) results with all fields or a subset (using `fields`), or paginated by storage order (using `cursor` or `since`) to access every record matching a query.\n \nParameters for records are specified as their own object structure, provided in the body of the request.", "parameters": [ { "name": "format", "in": "query", "description": "Choose the output format", "required": false, "schema": { "type": "string", "enum": ["json", "ndjson", "csv", "tsv"], "default": "json" } } ], "requestBody": { "required": true, "description": "Records query", "content": { "application/json": { "schema": { "type": "object", "properties": { "dataset_id": { "type": "string", "description": "Identifier of the dataset to query. Your authentication token must have permission to read from this dataset. If not specified, and you have access to the social dataset, the social dataset (id `ds_gj4u3F40SLa`) will be used." }, "timezone": { "type": "string", "description": "IANA timezone to use for interpreting input query times - NOT used on output", "default": "Etc/UTC" }, "query": { "$ref": "#/components/schemas/Query" }, "records": { "$ref": "#/components/schemas/RecordsQuery" } }, "required": [ "query", "records" ] }, "example": { "dataset_id": "ds_gj4u3F40SLa", "timezone": "Etc/UTC", "query": { "op": "contains", "fields": ["title", "body"], "value": "recipe" }, "records": { "size": 5 } } } } }, "responses": { "200": { "description": "Successful records response.\n \nThe result, if JSON, is an object, with the records themselves inside of an array keyed as `records`. If not flattened, this will be an array of objects, keyed by field IDs.\nAdditionally, a member in the result called `field_labels` provides labels for fields, keyed by the field ID.\nLastly of note is the member `value_labels`, which includes labels for values, in an object keyed by field id, each of which is an object keyed by value. These labels are typically only present for our own social data, and can be localized and translated." }, "400": { "description": "Your request has a problem.\n \nNote the response body for more information on what is wrong, and possibly how to fix it." }, "401": { "description": "Missing or invalid authentication.\n \nEnsure your provided Authorization token is correct and valid." }, "402": { "description": "Authentication credentials provided were valid, but one or more required permissions is missing, or access to one or more resources is lacking." }, "403": { "description": "Authentication failure.\n \nThere is a problem with the provided credentials. You likely lack permissions for the dataset used, or may need a new API token. Additional details may be provided in the response body." }, "413": { "description": "The request timed out. Likely due to taking too long to process. Should this unlikely error occur, try reducing the complexity of your query or narrowing the volume of results. Don't hesitate to reach out to support for assistance!" }, "500": { "description": "Server error.\n \nThere was an error handling your request. Feel free to wait a bit and try again. Note that any such errors are recorded, and notify our team - we will make every effort to fix any issues as quickly as possible." }, "503": { "description": "One or more backend services failed to respond, and we gave up waiting. Please wait a bit and try again. Don't hestitate to reach out to support for assistance." } } } }, "/query/topics": { "post": { "description": "# Topics\nTopics analyzes records to extract key words, phrases, links, emoji, flags, domains, #hashtags, and/or @mentions. This is a powerful, large-scale analysis performed on-demand, providing rich insight into the contents of the records matching the given query. Starscape's UI displays this data in word clouds, treemaps, and tables, and the analysis is key in understanding of data within a query.\n![Topics word cloud display of topics output](/api/docs/topics.png)\n \n### Clustering\nTopics performs clustering, building relationships between topics based on AI-driven semantic similarly and co-occurrence. This is provided via the `cluster_id` member in the results, each being a unique cluster of related topics. Additionally, topics can contain a `relationships` array, which lists other topics that topic is related to, along with the number of analyzed documents they co-occurred in, and the strength of the relationship.", "parameters": [ { "name": "format", "in": "query", "description": "Choose the output format", "required": false, "schema": { "type": "string", "enum": ["json", "csv", "tsv"], "default": "json" } } ], "requestBody": { "required": true, "description": "Topics query", "content": { "application/json": { "schema": { "type": "object", "properties": { "dataset_id": { "type": "string", "description": "Identifier of the dataset to query. Your authentication token must have permission to read from this dataset. If not specified, and you have access to the social dataset, the social dataset (id `ds_gj4u3F40SLa`) will be used." }, "query": { "$ref": "#/components/schemas/Query" }, "topics": { "$ref": "#/components/schemas/TopicsQuery" } }, "required": [ "query" ] }, "example": { "dataset_id": "ds_gj4u3F40SLa", "timezone": "Etc/UTC", "query": { "op": "contains", "fields": ["title", "body"], "value": "recipe" }, "topics": { "size": 5 } } } } }, "responses": { "200": { "description": "Successful topics response.\n \nThe result, if JSON, is an object, with the topics themselves inside of an array keyed as `topics`." }, "400": { "description": "Your request has a problem.\n \nNote the response body for more information on what is wrong, and possibly how to fix it." }, "401": { "description": "Missing or invalid authentication.\n \nEnsure your provided Authorization token is correct and valid." }, "402": { "description": "Authentication credentials provided were valid, but one or more required permissions is missing, or access to one or more resources is lacking." }, "403": { "description": "Authentication failure.\n \nThere is a problem with the provided credentials. You likely lack permissions for the dataset used, or may need a new API token. Additional details may be provided in the response body." }, "413": { "description": "The request timed out. Likely due to taking too long to process. Should this unlikely error occur, try reducing the complexity of your query or narrowing the volume of results. Don't hesitate to reach out to support for assistance!" }, "500": { "description": "Server error.\n \nThere was an error handling your request. Feel free to wait a bit and try again. Note that any such errors are recorded, and notify our team - we will make every effort to fix any issues as quickly as possible." }, "503": { "description": "One or more backend services failed to respond, and we gave up waiting. Please wait a bit and try again. Don't hestitate to reach out to support for assistance." } } } }, "/query/clusters": { "post": { "description": "# Clusters\nClusters performs unsupervised clustering of records, based on an AI-driven lexical semantic analysis of content. Results are labeled by groups of distinguishing key words and phrases, and include various metadata. This analysis can provide a powerful aid to understanding how records are related, and what key high-level groups they form.", "parameters": [ { "name": "format", "in": "query", "description": "Choose the output format", "required": false, "schema": { "type": "string", "enum": ["json", "csv", "tsv"], "default": "json" } } ], "requestBody": { "required": true, "description": "Clusters query", "content": { "application/json": { "schema": { "type": "object", "properties": { "dataset_id": { "type": "string", "description": "Identifier of the dataset to query. Your authentication token must have permission to read from this dataset. If not specified, and you have access to the social dataset, the social dataset (id `ds_gj4u3F40SLa`) will be used." }, "timezone": { "type": "string", "description": "IANA timezone to use for interpreting input query times - NOT used on output", "default": "Etc/UTC" }, "query": { "$ref": "#/components/schemas/Query" }, "clusters": { "$ref": "#/components/schemas/ClustersQuery" } }, "required": [ "query" ] }, "example": { "dataset_id": "ds_gj4u3F40SLa", "timezone": "Etc/UTC", "query": { "op": "contains", "fields": ["title", "body"], "value": "recipe" }, "clusters": { "size": 5 } } } } }, "responses": { "200": { "description": "Successful clusters response.\n \nThe result, if JSON, is an object, with the clusters themselves inside of an array keyed as `clusters`." }, "400": { "description": "Your request has a problem.\n \nNote the response body for more information on what is wrong, and possibly how to fix it." }, "401": { "description": "Missing or invalid authentication.\n \nEnsure your provided Authorization token is correct and valid." }, "402": { "description": "Authentication credentials provided were valid, but one or more required permissions is missing, or access to one or more resources is lacking." }, "403": { "description": "Authentication failure.\n \nThere is a problem with the provided credentials. You likely lack permissions for the dataset used, or may need a new API token. Additional details may be provided in the response body." }, "413": { "description": "The request timed out. Likely due to taking too long to process. Should this unlikely error occur, try reducing the complexity of your query or narrowing the volume of results. Don't hesitate to reach out to support for assistance!" }, "500": { "description": "Server error.\n \nThere was an error handling your request. Feel free to wait a bit and try again. Note that any such errors are recorded, and notify our team - we will make every effort to fix any issues as quickly as possible." }, "503": { "description": "One or more backend services failed to respond, and we gave up waiting. Please wait a bit and try again. Don't hestitate to reach out to support for assistance." } } } }, "/query/cluster-graph": { "post": { "description": "# Cluster Graph\nPerforms identical analysis to `/query/clusters`, but in addition to outputting cluster objects, this outputs minimal record information in an array of objects in the `nodes` result property, along with links used for constructing graphs between record nodes in arrays of objects in the `links` result property. The record objects include their ids, allowing retrieval of full records where desired.\n![Narratives force graph display of cluster-graph output](/api/docs/cluster-graph.png)", "requestBody": { "required": true, "description": "Records query", "content": { "application/json": { "schema": { "type": "object", "properties": { "dataset_id": { "type": "string", "description": "Identifier of the dataset to query. Your authentication token must have permission to read from this dataset. If not specified, and you have access to the social dataset, the social dataset (id `ds_gj4u3F40SLa`) will be used." }, "query": { "$ref": "#/components/schemas/Query" }, "clusters": { "$ref": "#/components/schemas/ClustersQuery" } }, "required": [ "query" ] }, "example": { "dataset_id": "ds_gj4u3F40SLa", "timezone": "Etc/UTC", "query": { "op": "contains", "fields": ["title", "body"], "value": "recipe" }, "clusters": { "size": 100 } } } } }, "responses": { "200": { "description": "Successful cluster graph response.\n \nThe result, if JSON, is an object, with the records themselves inside of an array keyed as `records`. If not flattened, this will be an array of objects, keyed by field IDs.\nAdditionally, a member in the result called `field_labels` provides labels for fields, keyed by the field ID.\nLastly of note is the member `value_labels`, which includes labels for values, in an object keyed by field id, each of which is an object keyed by value. These labels are typically only present for our own social data, and can be localized and translated." }, "400": { "description": "Your request has a problem.\n \nNote the response body for more information on what is wrong, and possibly how to fix it." }, "401": { "description": "Missing or invalid authentication.\n \nEnsure your provided Authorization token is correct and valid." }, "402": { "description": "Authentication credentials provided were valid, but one or more required permissions is missing, or access to one or more resources is lacking." }, "403": { "description": "Authentication failure.\n \nThere is a problem with the provided credentials. You likely lack permissions for the dataset used, or may need a new API token. Additional details may be provided in the response body." }, "413": { "description": "The request timed out. Likely due to taking too long to process. Should this unlikely error occur, try reducing the complexity of your query or narrowing the volume of results. Don't hesitate to reach out to support for assistance!" }, "500": { "description": "Server error.\n \nThere was an error handling your request. Feel free to wait a bit and try again. Note that any such errors are recorded, and notify our team - we will make every effort to fix any issues as quickly as possible." }, "503": { "description": "One or more backend services failed to respond, and we gave up waiting. Please wait a bit and try again. Don't hestitate to reach out to support for assistance." } } } }, "/query/omnibus": { "post": { "description": "# Omnibus\nThis endpoint can provide multiple different responses in a single endpoint. Omnibus can run aggs, output records, analyze topics, and run Narratives. Performing all of these together can make API implementation simpler, and improves performance. To use omnibus, you must ask for at least 2 results (for example, aggs and records), and can ask for all capabilities at once. Input and outputs of each match the individual endpoints, except that the response in Omnibus is a JSON object keyed by the endpoint, with the value of that object member being that response, otherwise identical. To specify what to run, pass the settings object in the request body. The object can even be empty to run the function with default settings (note: this is possible with aggs only if include_total is used.)\n\n## Notes\n- Omnibus is JSON-only\n- The records function in omnibus does not support use of `since` or `cursor`\n- If records `sort` is specified, the `sample_sort` used for topics and/or clusters will use the same sorting.\n\n## Billing\nOmnibus is logged and billed identically to the individual handlers.", "parameters": [ { "name": "include_total", "in": "query", "description": "If true, a numerical _total value will be added to the top-level agg output as the total results matching the input query.", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "flatten", "in": "query", "description": "Flattens the agg output format, returning an object with a series of flat arrays, rather than nested objects. This is only for aggs. To flatten records, use the request body option `flatten_output`.", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "fill_with_zero", "in": "query", "description": "When using flatten, this will fill missing values in the flattened arrays with 0, rather than null.", "required": false, "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "description": "Omnibus query", "content": { "application/json": { "schema": { "type": "object", "properties": { "dataset_id": { "type": "string", "description": "Identifier of the dataset to query. Your authentication token must have permission to read from this dataset. If not specified, and you have access to the social dataset, the social dataset (id `ds_gj4u3F40SLa`) will be used." }, "query": { "$ref": "#/components/schemas/Query" }, "aggs": { "$ref": "#/components/schemas/AggQuery" }, "records": { "$ref": "#/components/schemas/RecordsQuery" }, "topics": { "$ref": "#/components/schemas/TopicsQuery" }, "clusters": { "$ref": "#/components/schemas/ClustersQuery" } }, "required": [ "query" ] }, "example": { "dataset_id": "ds_gj4u3F40SLa", "timezone": "Etc/UTC", "query": { "op": "contains", "fields": ["title", "body"], "value": "recipe" }, "aggs": { "weekly histogram": { "op": "histogram", "field": "published", "interval": "week" } }, "records": { "size": 5 } } } } }, "responses": { "200": { "description": "Successful omnibus response.\n \nThe result, if JSON, is an object, with each response in a sub-object keyed by the endpoint name." }, "400": { "description": "Your request has a problem.\n \nNote the response body for more information on what is wrong, and possibly how to fix it." }, "401": { "description": "Missing or invalid authentication.\n \nEnsure your provided Authorization token is correct and valid." }, "402": { "description": "Authentication credentials provided were valid, but one or more required permissions is missing, or access to one or more resources is lacking." }, "403": { "description": "Authentication failure.\n \nThere is a problem with the provided credentials. You likely lack permissions for the dataset used, or may need a new API token. Additional details may be provided in the response body." }, "413": { "description": "The request timed out. Likely due to taking too long to process. Should this unlikely error occur, try reducing the complexity of your query or narrowing the volume of results. Don't hesitate to reach out to support for assistance!" }, "500": { "description": "Server error.\n \nThere was an error handling your request. Feel free to wait a bit and try again. Note that any such errors are recorded, and notify our team - we will make every effort to fix any issues as quickly as possible." }, "503": { "description": "One or more backend services failed to respond, and we gave up waiting. Please wait a bit and try again. Don't hestitate to reach out to support for assistance." } } } }, "/query/ai-summary": { "post": { "description": "# AI Summary\nThis powerful functionality analyzes your query using Topics, Narratives, Topic Clusters, and a wealth of information from Infegy IQ, like sentiment, emotion, and other metrics, along with selected documents, and sends this information to a state-of-the-art generative AI Large Language Model (LLM) to describe in natural language. In effect, it describes the query's results, in detail, in natural language!\n \nPlease note: This endpoint has a 15 requests per 2-minute sliding window rate limit.\n \nThis endpoint requires the AI package.", "requestBody": { "required": true, "description": "AI Summary query", "content": { "application/json": { "schema": { "type": "object", "properties": { "dataset_id": { "type": "string", "description": "Identifier of the dataset to query. Your authentication token must have permission to read from this dataset. If not specified, and you have access to the social dataset, the social dataset (id `ds_gj4u3F40SLa`) will be used." }, "timezone": { "type": "string", "description": "IANA timezone to use for interpreting input query times - NOT used on output", "default": "Etc/UTC" }, "query": { "$ref": "#/components/schemas/Query" } }, "required": [ "query" ] }, "example": { "dataset_id": "ds_gj4u3F40SLa", "query": { "op": "contains", "fields": ["title", "body"], "value": "election" } } } } }, "responses": { "200": { "description": "Successful AI Summary response.\n \nThe result is an object, with `total_count` returning the total query results, `analyzed_count` returning the total documents analyzed to generate the summary, and `summary`, the summary itself. Please note the `summary` will be formatted using Markdown." }, "400": { "description": "Your request has a problem.\n \nNote the response body for more information on what is wrong, and possibly how to fix it." }, "401": { "description": "Missing or invalid authentication.\n \nEnsure your provided Authorization token is correct and valid." }, "402": { "description": "Authentication credentials provided were valid, but one or more required permissions is missing, or access to one or more resources is lacking." }, "403": { "description": "Authentication failure.\n \nThere is a problem with the provided credentials. You likely lack permissions for the dataset used, or may need a new API token. Additional details may be provided in the response body." }, "413": { "description": "The request timed out. Likely due to taking too long to process. Should this unlikely error occur, try reducing the complexity of your query or narrowing the volume of results. Don't hesitate to reach out to support for assistance!" }, "429": { "description": "Rate limit reached\n \nYou've exceeded the rate limit allowed for this endpoint. Please wait a minute before trying again." }, "500": { "description": "Server error.\n \nThere was an error handling your request. Feel free to wait a bit and try again. Note that any such errors are recorded, and notify our team - we will make every effort to fix any issues as quickly as possible." }, "503": { "description": "One or more backend services failed to respond, and we gave up waiting. Please wait a bit and try again. Don't hestitate to reach out to support for assistance." }, "531": { "description": "The external AI LLM service used to generate the natural language portion of this response failed. Please try the request again." }, "533": { "description": "The external AI LLM service used to generate the natural language portion of this response is temporarily unavailable. Please wait a bit and try again." }, "539": { "description": "The external AI LLM service used to generate the natural language portion of this response is too busy to handle the request right now. Please wait a bit and try again." } } } }, "/query/ai-assist": { "get": { "description": "# AI Query Assist\nThis powerful tool builds complete, ready-to-use Query objects from natural language prompts. Simply describe what you want the query to match, and the endpoint will analyze data and use AI to build a complete, validated Query object. The response is simply a Query in JSON!\n \nThis endpoint requires the AI package.", "parameters": [ { "name": "prompt", "description": "The natural language prompt describing what you'd like the query to match.", "in": "query", "required": true, "example": "healthy foods", "schema": { "type": "string" } }, { "name": "allow_snippet", "description": "If this is true (the default), we will allow \"snippet\"-type queries, which otherwise may not be allowed - for example: exclusion-only queries.", "in": "query", "required": false, "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "Successful AI Assist response.\n \nThe result is a Query object, ready-to-use with any other query endpoint." }, "400": { "description": "Your request has a problem.\n \nNote the response body for more information on what is wrong, and possibly how to fix it." }, "401": { "description": "Missing or invalid authentication.\n \nEnsure your provided Authorization token is correct and valid." }, "402": { "description": "Authentication credentials provided were valid, but one or more required permissions is missing, or access to one or more resources is lacking." }, "403": { "description": "Authentication failure.\n \nThere is a problem with the provided credentials. You likely lack permissions for the dataset used, or may need a new API token. Additional details may be provided in the response body." }, "413": { "description": "The request timed out. Likely due to taking too long to process. Should this unlikely error occur, try reducing the complexity of your query or narrowing the volume of results. Don't hesitate to reach out to support for assistance!" }, "429": { "description": "Rate limit reached\n \nYou've exceeded the rate limit allowed for this endpoint. Please wait a minute before trying again." }, "500": { "description": "Server error.\n \nThere was an error handling your request. Feel free to wait a bit and try again. Note that any such errors are recorded, and notify our team - we will make every effort to fix any issues as quickly as possible." }, "503": { "description": "One or more backend services failed to respond, and we gave up waiting. Please wait a bit and try again. Don't hestitate to reach out to support for assistance." }, "531": { "description": "The external AI LLM service used to generate the natural language portion of this response failed. Please try the request again." }, "533": { "description": "The external AI LLM service used to generate the natural language portion of this response is temporarily unavailable. Please wait a bit and try again." }, "539": { "description": "The external AI LLM service used to generate the natural language portion of this response is too busy to handle the request right now. Please wait a bit and try again." } } } }, "/query/social-influencers": { "post": { "description": "# Social Influencers\nFind influential authors discussing any given input query. This uses an algorithm considering engagements, followers, general posting frequency, query matches, and sentiment to generate a ranked list of influential sources, or authors.\n \nThis endpoint works specifically and only with the social dataset.", "parameters": [ { "name": "format", "in": "query", "description": "Choose the output format", "required": false, "schema": { "type": "string", "enum": ["json", "csv", "tsv"], "default": "json" } } ], "requestBody": { "required": true, "description": "Influencers query", "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "$ref": "#/components/schemas/Query" }, "options": { "properties": { "size": { "description": "Number of results to return.", "type": "integer", "default": 50, "minimum": 1, "maximum": 1000 }, "min_hits": { "description": "Minimum number of query matches a source must have to be considered for the result set.", "type": "integer", "default": 2, "minimum": 1, "maximum": 1000 } } } }, "required": [ "query" ] }, "example": { "query": { "op": "contains", "fields": ["title", "body"], "value": "recipe" }, "options": { "size": 25 } } } } }, "responses": { "200": { "description": "Successful AI Assist response.\n \nThe result is a Query object, ready-to-use with any other query endpoint." }, "400": { "description": "Your request has a problem.\n \nNote the response body for more information on what is wrong, and possibly how to fix it." }, "401": { "description": "Missing or invalid authentication.\n \nEnsure your provided Authorization token is correct and valid." }, "402": { "description": "Authentication credentials provided were valid, but one or more required permissions is missing, or access to one or more resources is lacking." }, "403": { "description": "Authentication failure.\n \nThere is a problem with the provided credentials. You likely lack permissions for the dataset used, or may need a new API token. Additional details may be provided in the response body." }, "413": { "description": "The request timed out. Likely due to taking too long to process. Should this unlikely error occur, try reducing the complexity of your query or narrowing the volume of results. Don't hesitate to reach out to support for assistance!" }, "429": { "description": "Rate limit reached\n \nYou've exceeded the rate limit allowed for this endpoint. Please wait a minute before trying again." }, "500": { "description": "Server error.\n \nThere was an error handling your request. Feel free to wait a bit and try again. Note that any such errors are recorded, and notify our team - we will make every effort to fix any issues as quickly as possible." }, "503": { "description": "One or more backend services failed to respond, and we gave up waiting. Please wait a bit and try again. Don't hestitate to reach out to support for assistance." } } } }, "/suggest/{query_or_dataset_id}": { "get": { "description": "# Suggest\nThe suggest endpoint will provide prefix-based autocompletion suggestions for query inputs. This can be particularly useful for high-cardinality fields, or fields which have distinct IDs and labels, such as entities, countries, or languages. Provide a small amount of input, and the API will return the most likely completions for the given text, with both `id` (to use in a query) and `label` (for display to a user).\n \nThis API is localized and translated, where capable, such as metadata Infegy's analysis adds, like `country`, `entities`, `language`, and `sentiment`. Meaning if your user prefers the French language, or your Accept-Language header specifies French, for example, inputting \"Éta\" for `country` will suggest \"États-Unis\" - United States in French.\n \n![Suggest output example from Starscape UI](/api/docs/suggest.png)", "parameters": [ { "name": "query_or_dataset_id", "description": "The query or dataset ID for which we will suggest results.", "in": "path", "required": true, "example": "ds_gj4u3F40SLa", "schema": { "type": "string", "pattern": "^(q|ds)_[A-Za-z0-9]{8,16}$" } }, { "name": "field", "description": "Field ID from the dataset to suggest. Must be of type `keyword` or `keywords`.", "in": "query", "required": true, "example": "entities", "schema": { "type": "string" } }, { "name": "input", "description": "Prefix input for matching. We will find items starting with this input.", "in": "query", "required": true, "example": "joe", "schema": { "type": "string" } }, { "name": "size", "description": "The number of suggestions to return.", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 5, "required": false } } ], "responses": { "200": { "description": "Successful suggest response.\n \nThe result is a JSON object, with suggestions inside of an array member called `suggestions`. Each suggestion is an object with `id` (for passing in a query) and `label` (for display to a user)." }, "400": { "description": "Your request has a problem.\n \nNote the response body for more information on what is wrong, and possibly how to fix it." }, "401": { "description": "Missing or invalid authentication.\n \nEnsure your provided Authorization token is correct and valid." }, "402": { "description": "Authentication credentials provided were valid, but one or more required permissions is missing, or access to one or more resources is lacking." }, "403": { "description": "Authentication failure.\n \nThere is a problem with the provided credentials. You likely lack permissions for the dataset used, or may need a new API token. Additional details may be provided in the response body." }, "413": { "description": "The request timed out. Likely due to taking too long to process. Should this unlikely error occur, try reducing the complexity of your query or narrowing the volume of results. Don't hesitate to reach out to support for assistance!" }, "500": { "description": "Server error.\n \nThere was an error handling your request. Feel free to wait a bit and try again. Note that any such errors are recorded, and notify our team - we will make every effort to fix any issues as quickly as possible." }, "503": { "description": "One or more backend services failed to respond, and we gave up waiting. Please wait a bit and try again. Don't hestitate to reach out to support for assistance." } } } }, "/usage": { "get": { "description": "# Usage\nThe usage endpoint provides detailed information on your API usage, output as an overall total, as well as counts per token on your account.", "parameters": [ { "name": "since", "description": "Returns totals from this provided date, as an ISO-8601 datetime or duration, defaulting to the start of the current month.", "in": "query", "required": false, "schema": { "type": "string", "default": "-P0MF" } }, { "name": "until", "description": "Returns totals until this provided date, as an ISO-8601 datetime or duration, defaulting to now.", "in": "query", "required": false, "schema": { "type": "string", "default": "P0D" } } ], "responses": { "200": { "description": "Successful usage response.\n \nThe result is a JSON object, with per-api token results, as well as a total result." }, "400": { "description": "Your request has a problem.\n \nNote the response body for more information on what is wrong, and possibly how to fix it." }, "401": { "description": "Missing or invalid authentication.\n \nEnsure your provided Authorization token is correct and valid." }, "402": { "description": "Authentication credentials provided were valid, but one or more required permissions is missing, or access to one or more resources is lacking." }, "403": { "description": "Authentication failure.\n \nThere is a problem with the provided credentials. You likely lack permissions for the dataset used, or may need a new API token. Additional details may be provided in the response body." }, "413": { "description": "The request timed out. Likely due to taking too long to process. Should this unlikely error occur, try reducing the complexity of your query or narrowing the volume of results. Don't hesitate to reach out to support for assistance!" }, "500": { "description": "Server error.\n \nThere was an error handling your request. Feel free to wait a bit and try again. Note that any such errors are recorded, and notify our team - we will make every effort to fix any issues as quickly as possible." }, "503": { "description": "One or more backend services failed to respond, and we gave up waiting. Please wait a bit and try again. Don't hestitate to reach out to support for assistance." } } } } } }